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Foreword 



This manual describes several utility programs that aid the programmer and system 
designer in the software development process. Collectively, these utilities allow you 
to assemble 8080 assembly language modules, link them together to form an execut- 
able program, and generate a cross-reference listing of the variables used in a pro- 
gram. With these utilities, you can also create and manage your own libraries of 
object modules, as well as create large programs by breaking them into separate 
overlays. 

The Programmer's Utilities Guide assumes you are familiar with the CP/M® or 
MP/M II™ Operating System environment. It also assumes you are familiar with the 
basic elements of assembly language programming as described in the 8080 Assembly 
Language Programming Manual, published by Intel®. 

MAC™, the CP/M macro assembler, translates 8080 assembly language statements 
and produces a hex format object file suitable for processing in the CP/M environ- 
ment. MAC is upward compatible with the standard CP/M nonmacro assembler, 
ASM™. (See the CP/M documentation published by Digital Research.) 

MAC facilities include assembly of Intel 8080 microcomputer mnemonics, along with 
assembly-time expressions, conditional assembly, page formatting features, and a pow- 
erful macro processor compatible with the standard Intel definition. MAC also accepts 
most programs prepared for the Processor Technology Software #1 assembler, requiring 
only minor modifications. This revision is not compatible with previous versions. 

MAC is supplied on a standard disk, along with a number of library files. MAC 
requires about 12K of machine code and table space, along with an additional 2.5K 
of I/O buffer space. Because the BDOS portion of CP/M is coresident with MAC, the 
minimum usable memory size for MAC is about 20K. Any additional memory adds 
to the available Symbol Table area, allowing larger programs to be assembled. 

Sections 1 through 5 describe the simple assembler facilities of MAC: 8080 mne- 
monic forms, expressions, and conditional assembly. These facilities are similar to 
those of the CP/M assembler (ASM). If you are familiar with ASM, you might want 
to skip Sections 1 through 5 and begin with Section 6. 



ill 



Sections 6 through 8 describe MAC macro facilities in detail. Section 7 describes 
inline macros, and Section 8 explains the definition and evaluation of stored macros. 
If you are familiar with macros, briefly skim these sections, referring primarily to the 
examples. Section 9 explains macro applications, common macro forms, and pro- 
gramming practices. Skim the examples and refer back to the explanations for a 
detailed discussion of each program. 

Sections 10 through 13 describe other features of macro assembler operation. Sec- 
tion 10 details assembly parameters. Section 11 introduces iterative improvement, a 
common debugging practice used in developing macros and macro libraries. Section 
12 defines MAC's symbol storage requirements. 

Section 13 explains the differences between MAC and RMAC™, the CP/M Relo- 
cating Macro Assembler. 

Section 14 details XREF, an assembly language cross-reference program used with 
MAC and RMAC. 

Section 16 describes LINK-80™, the linkage editor that combines relocatable object 
modules into an absolute file ready to run under CP/M or MP/M II. Section 17 
describes how to use LINK-80, in conjunction with the PL/I-80™ compiler, to pro- 
duce overlays. Section 18 explains how to use LIB-80™, the software librarian for 
creating and manipulating library files containing object modules. 

The appendixes contain a complete list of error messages output by each of the 
utility programs. 
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Section 1 
Macro Assembler Operation 



Start MAC with a command of the form: 



MAC filename 



where filename corresponds to the assembly language file with an assumed filetype 
ASM. During the translation process, MAC creates a file called filename.HEX con- 
taining the machine code in the Intel hexadecimal format. You can subsequently load 
or test this HEX file. (See the LOAD command and the Dynamic Debugging Tool, 
DDT™, in the CP/M documentation.) MAC also creates a file named filename.PRN 
containing an annotated source listing, along with a file called filename. SYM contain- 
ing a sorted list of symbols defined in the program. 

Listing 1-1 provides an example of MAC output for a sample assembly language 
program stored on the disk under the name SAMPLE.ASM. Type MAC SAMPLE 
followed by a carriage return to execute the macro assembler. The PRN, SYM, and 
HEX files then appear as shown in the listing. The assembler listing file (PRN) 
includes a 16-column annotation at the left showing the values of literals, machine 
code addresses, and generated machine code. Note that an equal sign ( = ) is used to 
denote literal values to avoid confusion with machine code addresses. (See Section 
4.3.) Output files contain tab characters (ASCII CTRL-I) whenever possible to con- 
serve disk space. 

Source Program (SAMPLE.ASM) 

o r 3 1 h transient program area 

b d o s e =i u 5 h 5 b d o s entry p o i n t 

wchar equ 2 Iwrite character function 

5 enter with ccp's return address in the stack 

5 write a single character (?) and return 



m u 1 
w u i 
call 
ret 
e n d 



c twchar 
e * '?' 
b d o s 

lOOh 



write character function 
character to write 
write the character 
return to the c c p 
start address is 1 h 



Listing 1-1. Sample ASM, PRN, SYM, and HEX files from MAC 
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Assembler Listing File (SAMPLE.PRN) 



0100 




ORG 


100H 




0005 


= 


BD0S 


EOU 


0005H 


0002 




WCHAR 

5 

! 


EOU 

ENTER 

WRITE 


2 
WITH CCP': 
A SINGLE I 


0100 


0E02 




MVI 


C .WCHAR 


0102 


1E3F 




MVI 


£,'?' 


0104 


CD0500 




CALL 


BDOS 


0107 


C9 




RET 




0108 






END 


100H 



.TRANSIENT PROGRAM AREA 

5BD0S ENTRY POINT 

5WRITE CHARACTER FUNCTION 
S RETURN ADDRESS IN THE STACK 
CHARACTER (?) AND RETURN 

5WRITE CHARACTER FUNCTION 

5CHARACTER TO WRITE 

5WRITE THE CHARACTER 

iRETURN TO THE CCP 

5START ADDRESS IS 100H 



0005 BDOS 



Assembler Sorted Symbol File (SAMPLE.SYM) 

0002 WCHAR 



Assembler Hex Output File (SAMPLE.HEX) 



:080100000E021E3FCD0500C9EF 
:00010000FF 



Listing 1-1. (continued) 



End of Section 1 
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Section 2 
Program Format 



A program acceptable as input to the macro assembler consists of a sequence of 
statements of the form 

line# label operation operand comment 

where any or all of the elements can be present in a particular statement. Each 
assembly language statement terminates with a carriage return and line-feed. Note 
that the ED program automatically inserts the line-feed when you enter a carriage 
return. You can also terminate an assembly language statement by typing the excla- 
mation point (!) character. MAC treats this character as an end-of-line. You can 
write multiple assembly language statements on the same physical line if you separate 
them with exclamation points. 

A sequence of one or more blank or tab characters delimits statement elements. 
Tab characters are preferred because they conserve source file space and reduce the 
listing file size. The tab characters are not expanded until the file is printed or typed 
at the console. 

The line# is an optional decimal integer value representing the source program 
line number. It is allowed on any source line. The assembler ignores the optional 
line#. 

The label field takes the form: 

identifier 
or 

identifier: 

The label field is optional, except where noted in particular statement types. 

The identifier is a sequence of alphanumeric characters: alphabetics, question marks, 
commercial at-signs, and numbers, the first character of which is not numeric. You 
can use identifiers freely to label elements such as program steps and assembler 
directives, but identifiers cannot exceed 16 characters in length. 
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All characters are significant in an identifier, except for the embedded dollar sign 
($) that you can use to improve name readability. Further, MAC treats all lower-case 
alphabetics in an identifier as though they were upper-case. Note that the colon (:) 
following the identifier in a label is optional. The following examples are all valid 
labels: 



X 


XV 


Ion 3$name 


X? 


xv 1: 


1 o n a e r $n am e d $ d a t a 


xlx2 


13123: 


??@@abcDEF 


Gamma 


0GAMMA 


?ARE$WE$HERE? 



x234$5(378$9G 12*3456: 

The operation field contains an assembler directive (pseudo operation), 8080 machine 
operation code, or a macro invocation with optional parameters. The pseudo opera- 
tions and machine operation codes are described in Section 5. Macro calls are dis- 
cussed in Section 6. 

The operand field of the statement contains an expression formed from constant 
and label operands, with arithmetic, logical, and relational operations on these oper- 
ands. Properly formed expressions are detailed in Section 3. 

A leading semicolon character denotes the comment field, which contains arbitrary 
characters until the next carriage return or exclamation point character. MAC reads, 
lists, and otherwise ignores comment fields. To maintain compatibility with other 
assemblers, MAC also treats statements that begin with an asterisk (*) in column one 
as comment lines. 

The assembly language program is thus a sequence of statements of the form 
described above, terminated optionally by an END statement. The assembler ignores 
all statements following the END. 



End of Section 2 
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Section 3 
Forming the Operand 



Expressions in the operand field consist of simple operands — labels, constants, and 
reserved words — combined into properly formed subexpressions by arithmetic and 
logical operators. MAC carries out expression computation as the assembly proceeds. 
Each expression produces a 16-bit value during the assembly. The number of signifi- 
cant digits in the result must not exceed the intended use. That is, if an expression is 
to be used in a byte move immediate (see the MVI instruction), the absolute value of 
the operand must fit within an 8 -bit field. Instructions for each expression give the 
restrictions on expression significance. 



3.1 Labels 

A label is an identifier of a statement. The label's value is determined by the type 
of statement it precedes. If the label occurs on a statement that generates machine 
code or reserves memory space, such as a MOV instruction or a DS pseudo opera- 
tion, then the label is given the value of the program address it labels. If the label 
precedes an EQU or SET, then the label is given the value that results from evaluat- 
ing the operand field. In a macro definition, the label is given a text value, a sequence 
of ASCII characters, that is the body of the macro definition. With the exception of 
the SET and MACRO pseudo operations, an identifier can label only one statement. 

When a nonmacro label appears in the operand field, the assembler substitutes its 
16-bit value. This value can then be combined with other operands and operators to 
form the operand field for an instruction. When a macro identifier appears in the 
operation field of the statement, the text stored as the value of the macro name is 
substituted for the name. In this case, the operand field of the statement contains 
actual parameters. These are substituted for dummy parameters in the body of the 
macro definition. Later sections give the exact mechanisms for defining, calling, and 
substituting macro text. 
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3.2 Numeric Constants 

A numeric constant is a 16-bit value in a number base. A trailing radix indicator 
denotes the base, called the radix of the constant. The radix indicators are 

B binary constant (base 2) 

O octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 

Q is an alternate radix indicator for octal numbers because the letter O is easily 
confused with the digit 0. Any numeric constant that does not terminate with a radix 
indicator is assumed to be a decimal constant. 

A constant is composed of a sequence of digits, followed by an optional radix 
indicator, where the digits are in the appropriate range for the radix. Binary con- 
stants must be composed of and 1 digits. Octal constants can contain digits in the 
range 0-7. Decimal constants contain decimal digits. Hexadecimal constants contain 
decimal digits and hexadecimal digits A through F, corresponding to the decimal 
numbers 10 through 15. 

Note that the leading digit of a hexadecimal constant must be a decimal digit to 
avoid confusing a hexadecimal constant with an identifier. A leading prevents 
ambiguity. A constant composed in this manner produces a binary number that can 
be contained within a 16-bit counter, truncated on the right by the assembler. Like 
identifiers, embedded $ symbols are allowed within constants to improve readability. 

Finally, the radix indicator translates to upper-case if a lower-case letter is encoun- 
tered. The following examples are valid numeric constants: 



1234 


1234D 


1100B 


lill$0000*llll*0000B 


1234H 


0FFFEH 


33770 


33$77$220 


3377o 


Of e3h 


1234d 


Of f f f h 
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3.3 Reserved Words 

Several reserved character sequences have predefined meanings in the operand field 
of a statement. The names of 8080 registers and their values are given in Table 3-1. 



Table 3-1. 8080 Registers and Values 



symbol 


value 


symbol 


value 


A 


7 


B 





C 


1 


D 


2 


E 


3 


H 


4 


L 


5 


M 


6 


SP 


6 


PSW 


6 



Lower-case names have the same values as their upper-case equivalents. Machine 
instructions can also be used in the operand field, resulting in their internal codes. 
For instructions that require operands, where the operand is a part of the binary bit 
pattern of the instruction (e.g., MOV A,B), the value of the instruction is the bit 
pattern of the instruction, with zeros in the optional fields. For example, the statement 

LXI H»M0V 

assembles an LXI H instruction with an operand equal to 40H, the value of the 
MOV instruction with zeros as operands. 

When the $ symbol appears in the operand field — not embedded within identifiers 
and numbers — its value is the address of the beginning of the current instruction. For 
example, the two statements 



JMP 



and 



JMP $ 

produce a jump instruction to the current location. As an exception, the $ symbol at 
the beginning of a logical line can introduce assembly formatting instructions. (See 
Section 10.) 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



3.4 String Constants Programmer's Utilities Guide 

3.4 String Constants 

String constants represent sequences of graphic ASCII characters, enclosed in apos- 
trophes ('). All strings must be fully contained within the current physical line, with 
the exclamation point (!) character within strings treated as an ordinary string char- 
acter. Each individual string must not exceed 64 characters in length, or MAC reports 
an error. The apostrophe character can be included in a string by typing two apos- 
trophes ("). The assembler reads the two apostrophes as a single apostrophe. 

Note that particular operation codes can require the string length to be no longer 
than one or two characters. The LXI instruction, for example, accepts a character 
string operand of one or two characters. The CPI instruction accepts only a one- 
character string. The DB instruction, however, allows strings zero through 64 char- 
acters long in its list of operands. In the case of single-character strings, the value is 
the 8-bit ASCII code for the character, without case translation. Two-character strings 
produce a 16-bit value with the second character as the low-order byte and the first 
character as the high-order byte. For example, the string constant 'A' is equivalent to 
41H. The two-character string 'AB' produces the 16-bit value 4142H. The following 
are valid strings in MAC statements: 

'A' 'AB' 'ab' 'c' " " 'she said "hello"' 

Note: You can use the ampersand (&) character to cause evaluation of dummy 
arguments within macro expansions inside string quotes. Section 8 details the substi- 
tution process. 



3.5 Arithmetic, Logical, and Relational Operators 

MAC can combine the operands described above in algebraic notation using prop- 
erly formed operands, operators, and parenthesized expressions. The operators MAC 
recognizes in the operand field are listed below. 

■ a + b produces the arithmetic sum of a and b; +b is b. 

■ a-b produces the arithmetic difference between a and b; -b is 0-b. 

■ a* b is the unsigned multiplication of a by b. 

■ a/b is the unsigned division of a by b. 

■ a MOD b is the remainder after division of a by b. 

■ a SHL b produces a shifted left by b, with zero right fill. 
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3.5 Operators 



a SHR b produces a shifted right by b, with zero left fill. 

NOT b is the bit-by-bit logical inverse of b. 

a EQ b produces true if a equals b, false otherwise. 

a LT b produces true if a is less than b, false otherwise. 

a LE b produces true if a is less than or equal to b, false otherwise. 

a GT b produces true if a is greater than b, false otherwise. 

a GE b produces true if a is greater than or equal to b, false otherwise. 

a AND b produces the bitwise logical AND of a and b. 

a OR b produces the bitwise logical OR of a and b. 

a XOR b produces the logical exclusive OR of a and b. 

HIGH b is identical to b SHR 8 (high-order byte of b). 

LOW b is identical to b AND OFFH (low-order byte of b). 



The letters a and b represent operands that are treated as 16-bit unsigned quantities 
in the range 0-65535. All arithmetic operators produce a 16-bit unsigned arithmetic 
result. Relational operators produce a true (OFFFFH) or false (OO0OH) 16-bit result. 
Logical operators operate bit-by-bit on their operands producing a 16-bit result of 
16 individual bit operations. The HIGH and LOW functions always produce a 16- 
bit result with a high-order byte of zero. Table 3-2 lists arithmetic, logical, and 
relational operators. 



Table 3-2. Operators 



arithmetic 


relational 


logical 


+ 


EQ 


NOT 


- 


LT 


AND 


* 


LE 


OR 


/ 


GT 


XOR 


MOD 


GE 




SHL 


NE 




SHR 
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MAC performs all computations during the assembly process as 16-bit unsigned 
operations, as described above. The resulting expression must fit the operation code 
in which it is used. For example, the expression used in an ADI (add immediate) 
instruction must fit into an 8-bit field. Thus, the high-order byte must be zero. If the 
computed value does not fit the field, the assembler produces a value error for that 
statement. 

As an exception to this rule, negative 8 -bit values are allowed in 8 -bit fields under 
the following conditions: if the program attempts to fill an 8 -bit field with a 16-bit 
value that has all Is in the high-order byte, and the sign bit is set, then the high order 
byte is truncated, and no error is reported. This condition arises when a negative 
sign is placed in front of a constant. For example, the value -2 is defined and com- 
puted as 0-2, producing the 16-bit value OFFFEH, where the high-order byte (OFFH) 
contains extended sign bits that are all Is, and the low-order byte (OFEH) has the 
sign bit set. The following instructions do not produce value errors in MAC: 

ADI -1 ADI -15 ADI -127 ADI -128 ADI 0FF80H 
The following instructions produce value errors: 

ADI 25G ADI 327G8 ADI -129 ADI 0FF7FH 

The special operator NUL is used in conjunction with macro definition and expan- 
sion operations. The NUL operator takes a single operand. NUL must be the last 
operator in the operand field. 

Expressions can be formed from simple operands such as labels, numeric con- 
stants, string constants, and machine operation codes, or from fully enclosed paren- 
thesized expressions such as 

10+20 t 

10H+370* 

Ll/3» 

(L2 + 4) SHR 3* 

( 'a' and 5f h) + '0' *. 

( 'BB' + B) OR (PSW + M) t 

( 1+ (2 + C) ) shr (A-(B +1 ) ) » 

(HIGH A) SHR 3 

where blanks and tabs are ignored between the operators and operands of the 
expression. 
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3.6 Precedence of Operators 

MAC assumes operators have a relative precedence of application allowing expres- 
sions to be written without nested parentheses. The resulting expression has assumed 
parentheses that are defined by this relative precedence. The order of application of 
operators in unparenthesized expressions is listed below. Operators listed first have 
highest precedence. These are applied first in an unparenthesized expression. Opera- 
tors listed last have lowest precedence and are applied last. Operators listed on the 
same line have equal precedence and are applied from left to right as they are 
encountered in an expression: 

* / MOD SHL SHR 
+ 
EQ LT LE GT GE NE 
NOT 
AND 
OR XOR 
HIGH LO 

The following expressions are equivalent: 

a * b + c produces ( a * b ) + c 

a + b * c produces a + ( b * c ) 

a MOD b * c SHL d produces ( ( a MOD b ) * c ) SHL D 

a OR b AND NOT c + d SHL e produces 

a OR (b AND (NOT (c + (d SHL e)))> 



Balanced parenthesized subexpressions can always override the assumed parenthe- 
ses. The last expression above can be rewritten to force application of operators in a 
different order, as shown below: 

(a OR b) AND (NOT c) + d SHL e 
resulting in the assumed parentheses 

(a OR b) AND ((NOT c) + (d SHL e)) 

Note that an unparenthesized expression is well formed only if the expression that 
results from inserting the assumed parentheses is well formed. 
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Relational operators can be expressed in either of two forms, as shown in Table 
3-3. 



Table 3-3. Equivalent Forms 
of Relational Operators 



< 


LT 


< = 


LE 


= 


EQ 


< > 


NE 


> = 


GE 


> 


GT 



End of Section 3 
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Assembler Directives 



Assembler directives set labels to specific values during assembly, perform condi- 
tional assembly, define storage areas, and specify starting addresses in the program. 
Each assembler directive is denoted by a pseudo operation that appears in the oper- 
ation field of the statement. Table 4-1 lists the acceptable pseudo operations. 



Table 4-1. Pseudo Operations 



Directive 


Meaning 


ORG 


sets the program or data origin. 


END 


terminates the physical program. 


EQU 


performs a numeric equate. 


SET 


performs a numeric set or assignment. 


IF 


begins a conditional assembly. 


ELSE 


is an alternate to a previous IF. 


ENDIF 


marks the end of conditional assembly. 


DB 


defines data bytes or strings of data. 


DW 


defines words of storage (double bytes). 


DS 


reserves uninitialized storage areas. 


PAGE 


defines the listing page size for output. 


TITLE 


enables page titles and options. 



In addition to those listed above, several pseudo operations are used in conjunction 
with the macro processing facilities. MACRO, EXITM, ENDM, REPT, IRPC, IRP, 
LOCAL, and MACLIB are reserved words. They are fully described in Sections 7 
and 8. The nonmacro pseudo operations are detailed below. 
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4.1 The ORG Directive 

The ORG statement takes the form 

label ORG expression 

where label is an optional program label — an identifier followed by an optional 
colon (:) — and expression is a 16-bit expression consisting of operands defined before 
the ORG statement. The assembler begins machine code generation at the location 
specified in the expression. There can be any number of ORG statements within a 
program. There are no checks to ensure that you are not redefining overlapping 
memory areas. Note that most programs written for CP/M begin with an ORG 100H 
statement that causes machine code generation to begin at the base of the CP/M 
Transient Program Area. Programs assembled with RMAC and linked with LINK-80 
do not need an ORG 100H statement. (See Sections 13 and 15.) 

If the ORG statement has a label, then the label takes on the value given by the 
expression. The expression is the next machine code address to assemble. This label 
can then be used in the operand field of other statements to represent this expression. 

4.2 The END Directive 

The END statement is optional in an assembly language program; if present, it 
must be the last statement. All statements following the END are ignored. The two 
forms of the END statement are 

label END 

label END expression 

where the label is optional. If the first form is used, the assembly process stops, and 
the default starting address of the program is taken as 0000. Otherwise, the expres- 
sion is evaluated and becomes the program starting address. This starting address is 
included in the last record of the Intel format machine code hex file resulting from 
the assembly. Most CP/M assembly language programs end with the statement 

END 100H 

resulting in the default starting address of 100H, the beginning of the Transient 
Program Area. 
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4.3 The EQU Directive 

The EQU (equate) statement names synonyms for particular numeric values. The 
directive takes the form: 

label EQU expression 

The label must be present, and it must not label any other statement. The assembler 
evaluates the expression and assigns this value to the identifier given in the label field. 
The identifier is usually a name describing the value in a more human-oriented man- 
ner. You can use this name throughout the program as a parameter for certain 
functions. Suppose, for example, that data received from a teletype appears on an 
input port, and data is sent to the teletype through the next output port in sequence. 
The series of equate statements that can define these ports for a particular hardware 
environment is shown below. 



TTYBASE 


EQU 


10H 


5 BASE TTY 


PORT 


TTYIN 


EQU 


TTYBASE 


5 TTY DATA 


IN 


TTYOUT 


EQU 


TTYBASE+1 


5TTY DATA 


OUT 



At a later point in the program, the statements that access the teletype could appear 
as 

IN TTYIN 5READ TTY DATA TO A 
OUT TTYOUT 5WRITE DATA FROM A 

making the program more readable than the absolute I/O port addresses. If the 
hardware environment is later redefined to start the teletype communications ports 
at 7FH instead of 10H, the first statement need only be changed to 

TTYBASE EQU 7FH 5BASE PORT NUMBER FOR TTY 

and the program can be reassembled without changing any other statements. 
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4.4 The SET Directive 

The SET statement is similar to the EQU, taking the form 

label SET expression 

except that the label, taken as a variable name, can occur on other SET statements 
within the program. The expression is evaluated and becomes the current value 
associated with the label. Thus, unlike the EQU statement, where a label takes on a 
single value throughout the program, the SET statement can assign different values 
to a name at different parts of the program. In particular, the SET statement gives 
the label a value that is valid from the current SET statement to the point where the 
label occurs on the next SET statement. The use of SET is similar to the EQU, except 
that SET is used more often to control conditional assembly within macros. 

4.5 The IF, ELSE, and ENDIF Directives 

The IF, ELSE, and ENDIF directives define a range of assembly language state- 
ments to be included or excluded during the assembly process. The IF and ENDIF 
statements alone can bound a group of statements to be conditionally assembled, as 
shown in the following example: 

IF expression 

statement#l 

statement#2 

statement#n 
ENDIF 

Upon encountering the IF statement, the assembler evaluates the expression following 
the IF. All operands in the expression must be defined ahead of the IF statement. If 
the expression evaluates to a nonzero value, then statement#l through statement#n 
are assembled. If the expression evaluates to zero, then the statements are listed but 
not assembled. 

Conditional assembly is often used to write a single generic program that includes 
a number of possible alternative subroutines or program segments, where only a few 
of the possible alternatives are to be included in any given assembly. Listings 4-1 and 
4-2 give an example of such a program. 
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Assume that a console device, either a teletype or a CRT, is connected to an 8080 
microcomputer through I/O ports. Due to the electronic environment, the current 
loop teletype is connected through ports 10H and 11H, while the RS-232 CRT is 
connected through ports 20H and 21H. The program continually loops, reading and 
writing console characters. The program shown below operates either with a teletype 
or a CRT, depending on the value of the symbol TTY. 

Listing 4-1 shows an assembly for the teletype environment. Listing 4-2 shows the 
assembly for a CRT-based system. Note that the assembler leaves the leftmost 16 
columns blank when statements are skipped due to a false condition. 



CP/M MACRO ASSEM 2,0 



*00i 



Teletype Echo Program 



FFFF 


= 


TRUE 


EQU 


0FFFFH 


.DEFINE TRUE 


0000 


= 


FALSE 


EQU 


NOT TRUE 


5DEFINE FALSE 


FFFF 


= 


TTY 


EQU 


TRUE 


.SET TTY ON 


0010 


= 


TTYBASE 


EQU 


10H 


5BASE OF TTY PORTS 


0020 


= 


CRTBASE 


EQU 


20H 


iBASE OF CRT PORTS 








IF 


TTY 


.ASSEMBLE TTY PORTS 








TITLE 


'Teletype 


Echo ProSraw' 


0010 


= 


C0NIN 


EQU 


TTYBASE 


iCONSOLE INPUT 


0011 


= 


C0N0UT 


EQU 
ENDIF 


TTYBASE+1 


.CONSOLE OUT 








IF 


NOT TTY !i 


ASSEMBLE CRT PORTS 








TITLE 


'CRT Echo 


Program ' 






C0NIN 


EQU 


CRTBASE 


5C0NS0LE IN 






C0N0UT 


EQU 
ENDIF 


CRTBASE+1 


iCONSOLE OUT 


0000 


DB10 


ECHO: 


IN 


C0NIN 


5READ CONSOLE 
CHARACTER 


0002 


D311' 




OUT 


C0N0UT 


.WRITE CONSOLE 
CHARACTER 


0004 


C30000 




JMP 


ECHO 




0007 






END 







Listing 4-1. Conditional Assembly with TTY True 
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CP/M MACRO ASSEM 2,0 



•001 



CRT Echo Pros ram 



FFFF 


= 


TRUE 


EOU 


OFFFFH 


.DEFINE TRUE 




0000 


= 


FALSE 


EOU 


NOT TRUE 


.DEFINE FALSE 




0000 


= 


TTY 


EOU 


FALSE 


.SET CRT ON 




0010 


= 


TTYBASE 


EOU 


10H 


.BASE OF TTY PORTS 


0020 


= 


CRTBASE 


EOU 


20H 


5BASE OF CRT PORTS 








IF 


TTY 


.ASSEMBLE TTY 


PORTS 








TITLE 


'Teletype 


Echo Program' 








CONIN 


EOU 


TTYBASE 


5C0NS0LE 


INPUT 






CONOUT 


EOU 
ENDIF 


TTYBASE+1 


.CONSOLE 


OUT 








IF 


NOT TTY 


.ASSEMBLE CRT 


PORTS 








TITLE 


'CRT Echo 


Prosl rain ' 




0020 


= 


CONIN 


EOU 


CRTBASE 


.CONSOLE 


IN 


0021 


= 


CONOUT 


EOU 
ENDIF 


CRTBASE+1 


5C0NS0LE 


OUT 


0000 


DB20 


i 
ECHO: 


IN 


CONIN 


5READ CONSOLE 
CHARACTER 




0002 


D321 




OUT 


CONOUT 


5WRITE CONSOLE 












CHARACTER 




0004 


C30000 




JMP 


ECHO 






0007 






END 









Listing 4-2. Conditional Assembly with TTY False 
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The ELSE statement can be used as an alternative to an IF statement. The ELSE 
statement must occur between the IF and ENDIF statements. The form is 

IF expression 

statement#l 

statement#2 

statement#n 
ELSE 

statement#n + 1 
statement#n + 2 

statement#m 
ENDIF 

If the expression produces a nonzero (true) value, then statements 1 through n are 
assembled as before. However, the assembly process skips statements n + 1 through 
m. When the expression produces a zero value (false), MAC skips statements 1 
through n and assembles statements n + 1 through m. For example, the conditional 
assembly shown in Listings 4-1 and 4-2 can be rewritten as shown in Listing 4-3. 



CP/M MACRO ASSEM 2,0 



•001 



CRT Echo Program 



FFFF 


= 


TRUE 


EOU 


0FFFFH 


0000 


= 


FALSE 


EOU 


NOT TRUE 


0000 


= 


TTY 


EOU 


FALSE 


0010 


= 


TTYBASE 


EOU 


10H 


0020 




CRTBASE 


EOU 

IF 

TITLE 


20H 
TTY 
' T e 1 e t y p 






C0NIN 


EOU 


TTYBASE 






C0N0UT 


EOU 

ELSE 

TITLE 


TTYBASE+ 
'CRT Ech 


0020 


= 


C0NIN 


EOU 


CRTBASE 


0021 


= 


C0N0UT 


EOU 
ENDIF 


CRTBASE+ 


0000 


DB20 


1 

ECHO: 


IN 


C0NIN 


0002 


D321 




OUT 


C0N0UT 


0004 


C30000 




JMP 


ECHO 


0007 






END 





5DEFINE TRUE 

.DEFINE FALSE 

5 SET CRT ON 

iBASE OF TTY PORTS 

5BASE OF CRT PORTS 

5ASSEMBLE TTY PORTS 

e Echo Prosfram' 

.CONSOLE INPUT 
1 iCONSOLE OUT 
iASSEMBLE CRT PORTS 

Program' 

.CONSOLE IN 

1 .CONSOLE OUT 



5READ CONSOLE CHARACTER 
5WRITE CONSOLE CHARACTER 



Listing 4-3. Conditional Assembly Using ELSE for Alternate 
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Properly balanced IF, ELSE, and ENDIF statements can be completely contained 
within the boundaries of outer encompassing conditional assembly groups. The struc- 
ture outlined below shows properly nested IF, ELSE, and ENDIF statements: 

IF exp#l 

group#l 

IF exp#2 

group#2 

ELSE 

group#3 

ENDIF 

group#4 

ELSE 

group#5 

IF exp#3 

group#6 

ENDIF 

group#7 

ENDIF 

Groups 1 through 7 are sequences of statements to be conditionally assembled, and 
exp#l through exp#3 are expressions that control the conditional assembly. If exp#l 
is true, then group#l and group#4 are always assembled, and groups 5, 6, and 7 
are skipped. Further, if exp#l and exp#2 are both true, then group#2 is also included 
in the assembly. Otherwise, group#3 is included. If exp#l produces a false value, 
groups 1, 2, 3, and 4 are skipped, and groups 5 and 7 are always assembled. If 
exp#3 is true under these circumstances, then group#6 is also included with 5 and 
7. Otherwise, it is skipped in the assembly. A structure similar to this is shown in 
Listing 4-4, where literal true/false values show conditional assembly selection. 
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There can be up to eight pending IFs or ELSEs with unresolved ENDIFs at any 
point in the assembly, but the assembly usually becomes unreadable after two or 
three levels or nesting. The nesting level restriction also holds, however, for pending 
IFs and ELSEs during macro evaluation. Nesting level overflow produces an error 
during assembly. 



FFFF 


= 


TRUE 


EOU 


0FFFFH 


iDEFINE TRUE 


0000 




FALSE 


EOU 
IF 
MUI 
IF 

mi 

ELSE 

MUI 

ENDIF 

MUI 

ELSE 


NOT TRUE 

FALSE 

Ail 

TRUE 

Ai2 

Ai3 

A»4 


5DEFINE FALSE 


0000 


3E05 




MUI 
IF 


Ai5 
TRUE 




0002 


3E0G 




MUI 
ELSE 
MUI 
ENDIF 


Ai6 
A»7 




0004 


3E08 




MUI 

ENDIF 

END 


A»8 





Listing 4-4. Sample Program Using Nested IF, ELSE, and ENDIF 



4.6 The DB Directive 

The DB directive defines initialized storage areas in single-precision (byte) format. 

The statement form is 

label DB e#l, e#2, . . . , e#n 

where the label is optional, and e#l through e#n are either expressions that produce 
8-bit values (the high-order eight bits are zeros, or the high-order nine bits are ones), 
or are ASCII strings no longer than 64 characters each. There is no practical restric- 
tion on the number of expressions included on a single source line. The assembler 
evaluates expressions and places them into the machine code sequentially following 
the last program address generated. 
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String characters are similarly placed into memory, starting with the first character 
and ending with the last character. Strings longer than two characters cannot be used 
as operands in more complicated expressions. They must stand alone between the 
commas. Note that ASCII characters are always placed in memory with the high- 
order (parity) bit reset to zero. Further, recall that there is no translation from lower 
to upper-case within strings. The optional label can be used to reference the data 
area throughout the program. The following are examples of valid DB statements: 

data: DB 0»i»2»3»4»5»6 

DB data and Of f h »5 >377Q * 1+2 + 3+4 

s i 3n o n : DB 'please type your n am e : ' » c r * 1 f » 

DB 'AB' SHR 8» 'C'» 'DE' AND 7FH 

DB HIGH data* LOW (si anon GT data) 



4.7 The DW Directive 

The DW statement is similar to the DB statement except double-precision (two- 
byte) words of storage are initialized. The form of the DW statement is 

label DW e#l, e#2, . . . , e#n 

where the label is optional, and e#l through e#n are expressions that produce 16- 
bit values. Note that ASCII strings one or two characters long are allowed, but 
strings longer that two characters are disallowed. In all cases, the data storage is 
consistent with the 8080 processor; the least significant byte of the expression is 
stored first in memory, followed by the most significant byte. The following are 
examples of properly formed DW statements: 

do ub: DW Offefh* doub+4» s i snon-* »255+255 

DW 'a't 5. 'AB'» 'CD'» doub LT si anon 
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4.8 The DS Directive 

The DS statement reserves an area of uninitialized memory and takes the form 

label DS expression 

where the label is optional. The assembler begins subsequent code generation after 
the area reserved by the DS. Thus, the DS statement given above has exactly the 
same effect as the statement sequences: 

label: EQU $ ;CURRENT CODE LOC 

ORG $ + expression ;MOVE PAST AREA 



4.9 The PAGE and TITLE Directives 

The PAGE and TITLE pseudo operations give you control over the output format- 
ting that is sent to the PRN file or directly to the printer device. The forms for the 
PAGE statement are 

PAGE 

PAGE expression 

If the PAGE statement stands alone, an ASCII CTRL-L (form-feed) is sent to the 
output file after the PAGE statement has been printed. The PAGE command is often 
issued directly ahead of major sections of an assembly language program, such as a 
group of subroutines, to cause the next statement to appear at the top of the follow- 
ing page. 

The second form of the PAGE command specifies the output page size. In this case, 
the expression following the PAGE pseudo operation determines the number of out- 
put lines to be printed on each page. If the expression is zero, there are no page 
breaks. The print file is simply a continuous sequence of annotated output lines. If 
the expression is nonzero, then the page size is set to the value of the expression. 
Form-feeds are issued to cause page ejects when this count is reached for each page. 
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The assembler initially assumes that 
PAGE 56 

is in effect, producing a page eject at the beginning of the listing and at each 56-line 
increment. 

The TITLE directive takes the form 

TITLE string-constant 

where the string-constant is an ASCII string enclosed in apostrophes, not exceeding 
64 characters in length. If a TITLE pseudo operation is given during the assembly, 
each page of the listing file is prefixed with the title line, preceded by a standard 
MAC header. The title line thus appears as 

CP/M MACRO ASSEM n.n #ppp string-constant 

where n.n is the MAC version number, #ppp is the page number in the listing, and 
string-constant is the string given in the TITLE pseudo operation. MAC initially 
assumes that the TITLE operation is not in effect. When specified, the title line and 
the blank line following the title are not included in the line count for the page. No 
more than one TITLE statement is included in a program. Similarly, only one PAGE 
statement with the expression option is included. 

If a TITLE statement is included, and the Symbol Table is being appended to the 
PRN file (see Section 10), then the SYM file also contains the title at the beginning 
of the symbol listing with page breaks given by either the default or specified value 
of the PAGE statement. 
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4.10 A Sample Program Using Pseudo Operations 

The program in Listing 4-5 demonstrates the pseudo operations available in MAC. 
The sample program, called TYPER, operates in the CP/M environment by selecting 
one of three messages for output at the console. This program is created using the 
ED program, assembled using MAC, and then placed into COM file format using 
the CP/M LOAD function. After these steps have been accomplished, TYPER exe- 
cutes at the Console Command Processor level of CP/M by typing one of the 
commands: 

TYPER A 
TYPER B 
TYPER C 

to select message A, B, or C for printing. The TYPER program loads under the CCP 
and jumps to the label START where the 8080 stack is initialized. The TYPER 
program then prints its sign-on message: 

' t v p e r ' version 1 ♦ 

The program then retrieves the first character typed at the console following the 
command TYPER. This character should be A, B, or C. If one of these letters is not 
specified, then TYPER reboots the CP/M system to give control back to the CCP. If 
a valid letter is provided, TYPER selects one of the three messages (MESS @ A, 
MESS@B, or MESS@C) and prints it at the console before returning to CP/M. 

The TITLE and PAGE statements produce a title at the beginning of each page; 
page size is 33 lines, excluding the title lines. Form-feeds are suppressed. A number 
of EQU statements at the beginning improve program readability. Note that through- 
out the program the exclamation point allows several simple assembly language 
statements on the same line. Although multiple statements make the program more 
compact, they often decrease the overall readability of the source program. Note also 
that the program terminates without the END statement. The END statement is 
necessary only if a starting address is specified. The END statement is often included, 
however, to maintain compatibility with other assemblers. 

The DB statements labeled by SIGNON contain simple strings of characters and 
expressions that produce single-byte values. The DW statement following TABLE 
defines the base address of each string, corresponding to A, B, and C. Finally, the DS 
statement at the end of the program reserves space for the stack defined within the 
TYPER program. 
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CP/M MACRO ASSEM 2.0 #001 Typer Program 



000A 
0000 
0005 
005C 
0002 
000D 
000A 
0010 



TITLE 'Typer Program' 

PAGE 33 

5 PRINT THE MESSAGE SELECTED BY THE INPUT COMMAND AtB, OR C 

VERS EQU 10 .VERSION NUMBER N.N 

BOOT EQU OOOOH 5REB00T ENTRY POINT 

BDOS EQU 0005H !BDOS ENTRY POINT 

TFCB EQU 005CH iDEFAULT FILE CONTROL BLOCK (GET A»B» OR C) 

WCHAR EQU 2 .WRITE CHARACTER FUNCTION 

CR EQU ODH 5CARRIAGE RETURN CHARACTER 

LF EQU OAH 5LINE FEED CHARACTER 

STKSI2 EQU IS 5SIZE OF LOCAL STACK (IN DOUBLE BYTES) 



0100 

0100 C31201 



ORG 
JMP 



100H 
START 



50RIGIN AT 
5JUMP PAST 



BASE OF TPA 

THE MESSAGE SUBROUTINE 



WMESSAGE: 



0103 7EB7C8 
01 OS 5FOE02E5 
010A CD0500E1 
010E 23C30301 



iWRITE THE STRING AT THE ADDRESS GIVEN BY HL 'TIL 00 
MOV A,M! ORA A! RZ 5RETURN IF AT 00 
MOV E»A! MVI CWCHAR! PUSH H 5READY TO PRINT 
CALL BDOS! POP H 5CHARACTER PRINTED* GET NEXT 
INX H! JMP WMESSAGE 



START: 5ENTER HERE FROM THE CCP. RESET TO LOCAL STACK 

0112 31C101 LXI SP. STACK .SET TO LOCAL STACK 

0115 213701 LXI H»SIGNON iWRITE THE MESSAGE 

0118 CD0301 CALL WMESSAGE i 'TYPER' VERSION N.N 



01 IB 3A5D00 
011E DG41 
0120 FE03 
0122 D20000 



LDA 
SUI 
CPI 
JNC 



TFCB+1 
'A' 

TABLEN 
BOOT 



iGET FIRST CHAR TYPED AFTER NAME 
".NORMALIZE TO 0,1 ,2 
.COMPARE WITH THE TABLE LENGTH 
iREBOOT IF NOT VALID 



COMPUTE INDEX INTO ADDRESS TABLE BASED ON A'S VALUE 



Listing 4-5. TYPER Program Listing 
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CP/M MACRO ASSEM 2.0 



#002 



Typer Program 



0125 


5F 


0126 


1600 


0128 


214D01 


012B 


19 


012C 


19 


012D 


5E 


012E 


23 


012F 


56 


0130 


EB 


0131 


CD0301 


0134 


C30000 



MOV 

MVI 

LXI 

DAD 

DAD 

MOV 

INX 

MOV 

XCHG 

CALL 

JMP 



EiA 

DiO 

Hi TABLE 

D 

D 

EiM 

H 

DiM 

WMESSAGE 
BOOT 



5L0W ORDER INDEX 
iEXTENDED TO DOUBLE PRECISION 
5BASE OF THE TABLE TO INDEX 
5SINGLE PRECISION INDEX 
iDOUBLE PRECISION INDEX 
iLOW ORDER BYTE TO E 

5HIGH ORDER MESSAGE ADDRESS TO DE 
5READY FOR PRINTOUT 

5MESSAGE WRITTEN TO CONSOLE 

5REB00T. GO BACK TO CCP LEVEL 



SIGNON: 



0137 


2774737065 


DB 


0147 


312E30 


DB 


014A 


ODOAOO 

5 

TABLE: 


DB 

;o 


014D 


5301670182 


DW 


0003 


TABLEN 


EO 


0153 


7468S97320MESSiA: 


DB 


0167 


796F752073MESS@B: 


DB 


0182 


746869732OMESS0C: 


DB 



DATA AREAS 



'''typer'' v e rs i on ' 

VERS/lO+'O'i ','t VERS MOD 10 +'0' 

CR»LF»0 iEND OF MESSAGE 

JOF MESSAGE BASE ADDRESSES 

MESS@A»MESSiB»MESSiC 
(*-TABLE)/2 5LENGTH OF TABLE 

'this is message a'»CR»LFtO 

'you selected b this time ' >CR »LF »0 

'this message conies out for c'tCR»LF>0 



01A1 



STACK! 



DS 



STKSIZ*2 



.RESERVES AREA FOR STACK 



Listing 4-5. (continued) 



End of Section 4 
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Section 5 
Operation Codes 



Operation codes, found in the operation field of the statement, form the principal 
components of assembly language programs. MAC accepts all the standard mnemon- 
ics for the Intel 8080 microcomputer. These standard mnemonics are detailed in the 
8080 Assembly Language Programming Manual, published by Intel. Labels are optional 
on each input line and, if included, take the value of the instruction address immedi- 
ately before the instruction is issued by the assembler. The individual operators are 
listed briefly in the following sections. See the Intel documentation for exact operator 
details. In this section, operation codes are categorized for discussion; a sample assembly 
shows the hexadecimal codes produced for each operation. The following notation is 
used throughout: 

e3 represents a 3-bit value in the range 0-7 that usually takes one of the 

predefined register values A, B, C, D, H, L, M, SP, or PSW 

e8 represents an 8-bit value in the range 0-255; signed 8-bit values are 

also allowed in the range - 128 through + 127 

el 6 represents a 16-bit value in the range 0-65535 

where e3, e8, and el 6 can be formed from an arbitrary combination of operands 
and operators in a well-formed expression. In some cases, the operands are restricted 
to particular values within the range, such as the PUSH instruction. 
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5.1 Jumps, Calls, and Returns 

In some cases, the condition flags are tested to determine whether or not to take 
the jump, call, or return. The forms are shown below. The jump instructions are 



JMP el6 


JNZ el6 


JZel6 


JNC el 6 


JCel6 


JPO el6 


JPE el6 


JPel6 


JMel6 



The call instructions are 



CALL el 6 


CNZ el6 


CZel6 


CNC el6 


CCel6 


CPO el6 


CPE el6 


CPel6 


CMel6 



The return instructions are 



RET RNZ 


RZ 


RNC RC 


RPO 


RPE RP 


RM 


The restart instruction takes the form: 




RSTe3 





and performs exactly the same function as the instruction CALL e3*8 except that 
RST e3 requires only one byte of memory. 

Listing 5-1 shows the hexadecimal codes for each instruction, along with a short 
comment on each line describing the function of the instruction. 



30 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



5.1 Jumps, Calls, and Returns 



CP/M MACRO ASSEM 2.0 



TITLE 



SI 



•001 8080 JUMPS. CALLS. AND RETURNS 



'8080 JUMPS. CALLS. AND RETURNS' 



JUMPS ALL REQUIRE A IB-BIT OPERAND 



0000 


C31B00 


JMP 


LI 


5JUMP 


UNCONDITIONALLY TO LABEL 


0003 


C25C00 


JNZ 


Ll+'A' 


5JUMP 


ON 


NON ZERO 


TC 


LABEL 


OOOG 


CA0001 


JZ 


100H 


5JUMP 


ON 


ZERO CONDITION TO LABEL 


0003 


D21F00 


JNC 


Ll+4 


UUMP 


ON 


NO CARRY 


TC 


LABEL 


OOOC 


DA4142 


JC 


'AB' 


;jump 


ON 


CARRY TO 


LABEL 


OOOF 


E21700 


JPO 


$+8 


5JUMP 


ON 


PARITY ODD 


TO LABEL 


0012 


EAODOO 


JPE 


Ll/2 


;jump 


ON 


EVEN PARITY 


TO LABEL 


0015 


F24100 


JP 


GAMMA 


5JUMP 


ON 


POSITIVE 


RESULT TO LABEL 


0018 


FA1B00 JM 
LI: 


LOW LI 


5JUMP 


ON 


MINUS TO 


LABEL 




5 
5 


CALL 


OPERATIONS 


ALL REQUIRE A 16- 


BIT 


OPERAND 


001B 


CD3G00 


CALL 


SI 


5CALL 


SUBROUTINE 


UNCONDITIONALLY 


001E 


C43800 


CNZ 


Sl+X 


iCALL 


SUBROUTINE 


IF 


NON ZERO FLAG 


0021 


CC0001 


CZ 


100H 


.CALL 


SUBROUTINE 


IF 


ZERO FLAG 


0024 


D43A00 


CNC 


Sl+4 


5CALL 


SUBROUTINE 


IF 


NO CARRY FLAG 


0027 


DCOOOO 


CC 


SI MOD 3 


iCALL 


SUBROUTINE 


IF 


CARRY FLAG 


002A 


E43200 


CPO 


$+8 


5CALL 


SUBROUTINE 


IF 


PARITY ODD 


002D 


EC0300 


CPE 


Sl-$ 


5CALL 


SUBROUTINE 


IF 


PARITY EVEN 


0030 


F44100 


CP 


GAMMA 


5CALL 


SUBROUTINE 


IF 


POSITIVE 


0033 


FC4100 


CM 


GAM*MA 


iCALL 


SUBROUTINE 


IF 


MINUS FLAG 



PROGRAMMED RESTART (RST) REQUIRES 3-BIT OPERAND 







(RST X 


IS EQUIVALENT TO CALL X*8) 


003S 


C7 


RST 





5RESTART TO LOCATION 


0037 


DF 


RST 


X+l 










RETURN 


INSTRUCTIONS HAVE NO OPERAND 


0038 


C9 


RET 




5RETURN FROM SUBROUTINE 


0039 


CO 


RNZ 




5RETURN IF 


NON ZERO 


003A 


C8 


RZ 




5RETURN IF 


ZERO FLAG SET 


003B 


DO 


RNC 




5RETURN IF 


NO CARRY FLAG 


003C 


D8 


RC 




5RETURN IF 


CARRY FLAG SET 


003D 


EO 


RPO 




5RETURN IF 


PARITY IS ODD 


003E 


E8 


RPE 




5RETURN IF 


PARITY IS EVEN 


003F 


FO 


RP 




5RETURN IF 


POSITIVE RESULT 


0040 


F8 


RM 




5RETURN IF 


MINUS FLAG SET 


0002 


» 

X 
Gf 


EQU 
WMA: 


2 







0041 



END 



Listing 5-1. Assembly Showing Jumps, Calls, Returns, and Restarts 
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5.2 Immediate Operand Instructions 

Several instructions load single- or double-precision registers or single-precision 
memory locations with constant values. Other instructions perform immediate arith- 
metic or logical operations on the accumulator (register A). The move immediate 
instruction takes the form: 

MVI e3,e8 

where e3 is the register to receive the data given by the value e8. The expression e3 
must produce a value corresponding to one of the registers A, B, C, D, E, H, L, or 
the memory location M, which is addressed by the HL register pair. 

The accumulator immediate operations take the form: 



e8 


ACIe8 


SUIe8 


SBIe8 


e8 


XRIe8 


ORIe8 


CPIe8 



where the operation is always performed on the accumulator using the immediate 
data value given by the expression e8. 

The load extended immediate instructions take the form: 

LXI e3,el6 

where e3 designates the register pair to receive the double-precision value given by 
el 6. The expression e3 must produce a value corresponding to one of the double- 
precision register pairs B, D, H, or SP. 
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5.2 Immediate Operand Instructions 



Listing 5-2 shows the accumulator immediate operations in an assembly language 
program and briefly describes each instruction. 



CP/M MACRO ASSEM 2.0 



*001 



IMMEDIATE OPERAND INSTRUCTIONS 



TITLE 



'IMMEDIATE OPERAND INSTRUCTIONS' 



0000 0BFF 

! 


MVI 


5 

0002 CG01 


ALL 
ADI 


0004 CEFF 


ACI 


OOOB DB13 


SUI 


0008 DE10 


SBI 


000A E602 


ANI 


000C EE3C 


XRI 


OOOE FBFD 


ORI 



LI 



0010 



MVI USES A REGISTER (3-BIT) OPERAND AND 8-BIT DATA 
B.255 5M0VE IMMEDIATE A »B .C »D »E »H »L >M 

ALL REMAINING IMMEDIATE OPERATIONS USE A REGISTER 
1 5ADD IMMEDIATE TO A W/0 CARRY 
OFFH 5ADD IMMEDIATE TO A WITH CARRY 
Ll+3 5SUBTRACT FROM A W/0 BORROW (CARRY) 
LOW LI 5SUBTRACT FROM A WITH BORROW (CARRY) 
$ AND 7 5LOGICAL AND WITH IMMEDIATE DATA 
illl*OOB!LOGICAL XOR WITH IMMEDIATE DATA 
-3 5L0GICAL OR WITH IMMEDIATE DATA 



END 



Listing 5-2. Assembly Using Immediate Operand Instructions 



5.3 Increment and Decrement Instructions 

The 8080 set includes instructions for incrementing or decrementing single- and 
double-precision registers. The instruction forms for single-precision registers are 

INR e3 DCR e3 

where e3 produces a value corresponding to register A, B, C, D, H, L, or M. These 
registers correspond to the byte value at the memory location addressed by HL. The 
double-precision instructions are 

INXe3 DCXe3 

where e3 must be equivalent to one of the double-precision register pairs B, D, H, or 
SP. 
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Listing 5-3 shows a sample assembly language program using both single- and 
double-precision increment and decrement operations. 

CP/M MACRO ASSEM 2.0 *001 INCREMENT AND DECREMENT INSTRUCTIONS 

TITLE 'INCREMENT AND DECREMENT INSTRUCTIONS' 
i 
! INSTRUCTIONS REQUIRE REGISTER (3-BIT) OPERAND 

0000 1C INR E 5BYTE INCREMENT A ,B »C »D >E »H »L »M 

0001 3D DCR A 5BYTE DECREMENT A »B »C »D »E »H »L »M 

0002 33 INX SP ; 16-BIT INCREMENT B.D.H»SP 



INR 


E 


DCR 


A 


INX 


SP 


DCX 


B 


END 





0003 OB DCX B 516-BIT DECREMENT B ,0 >H »SP 

0004 



Listing 5-3. Assembly Containing Increment 
and Decrement Instructions 



5.4 Data Movement Instructions 

A number of 8080 instructions move data from memory to the CPU and from the 
CPU to memory. Data movement instructions also include a number of register-to- 
register move operations. The single-precision move register instruction takes the 
form: 

MOV e3, e3' 

where the e3 and e 3' expressions each produce a single-precision register A, B, C, D, E, H, 
L, or M, where the M register corresponds to the memory location addressed by HL. The 
register named by e3 always receives the 8-bit value given by the register expression e3'. 
The instruction is often read as move to register e3 from register e3'. The instruction 
MOV B,H would thus be read as move to register B from register H. Note that the 
instruction MOV M,M is not allowed. 

The single-precision load and store extended operations take the form: 

LDAX e3 STAX e3 

where e3 is a register expression that must produce one of the double-precision 
register pairs B or D. The 8-bit value in register A is either loaded from (LDAX) or 
stored to (STAX) the memory location addressed by the specified register pair. 
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The load and store direct instructions operate on either the A register for single- 
precision operations, or on the HL register pair for double-precision operations. 
Load and store direct instructions take the form: 

LHLDel6 SHLD el6 LDA el6 STA el6 

where el 6 is an expression that produces the memory address to obtain (LHLD, 
LDA) or store (SHLD, STA) the data value. 

The stack pop and push instructions perform double-precision load and store oper- 
ations, with the 8080 stack as the implied memory address. The forms are 

POP e3 PUSH e3 

where e3 must evaluate to one of the double-precision register pairs PSW, B, D, or 
H. 

The input and output instructions are also in this category, even though they 
receive and send their data to the electronic environment external to the 8080 pro- 
cessor. The input instruction reads data to the A register; the output instruction sends 
data from the A register. In both cases, the data port is given by the data value that 
follows the instruction. The forms are 

IN e8 OUT e8 

A set of instructions transfers double-precision values between registers and the 
stack. These instructions are 

XTHL PCHL SPHL XCHG 

Listing 5-4 lists these instructions in an assembly language program and briefly describes 
them. 
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CP/M MACRO ASSEM 2,0 *001 DATA/MEMORY/REGISTER HOVE OPERATIONS 
TITLE 'DATA/MEMORY/REGISTER MOVE OPERATIONS' 



0000 78 



THE MOV INSTRUCTION REQUIRES TWO REGISTER OPERANDS 
(3-BITS) SELECTED FROM A>B>C»DtE»H> OR M (M»M INVALID) 
MOV A,B 5M0VE DATA TO FIRST REGISTER FROM 
5SEC0ND 



0001 


OA 


0002 


12 


0003 


2A1900 


OOOB 


221 BOO 


0009 


3A1900 


OOOC 


32G400 


OOOF 


Fl 


0010 


C5 


0011 


DBOB 


0013 


D3FE 


0015 


E3 


00 IB 


E9 


0017 


F9 


0018 


EB 


0019 




00 IB 




0004 


= 


00 ID 





Dl 



LOAD/STORE EXTENDED REQUIRE REGISTER PAIR B OR D 
LDAX B iLOAD ACCUM FROM ADDRESS GIVEN BY BC 
STAX D iSTORE ACCUM TO ADDRESS GIVEN BY DE 

LOAD/STORE DIRECT REQUIRE MEMORY ADDRESS 

LHLD Dl iLOAD HL DIRECTLY FROM ADDRESS Dl 

SHLD Dl+2 ISTORE HL DIRECTLY TO ADDRESS Dl+2 

LDA Dl iLOAD THE ACCUMULATOR FROM Dl 

STA Dl SHL 25STORE THE ACCUMULATOR TO Dl SHL 2 

PUSH AND POP REQUIRE PSW OR REGISTER PAIR FROM B.D.H 
POP PSW iLOAD REGISTER PAIR FROM STACK 
PUSH B iSTORE REGISTER PAIR TO THE STACK 

INPUT/OUTPUT INSTRUCTIONS REQUIRE 8-BIT PORT NUMBER 
IN X+2 iREAD DATA FROM PORT NUMBER TO A 
OUT OFEH iWRITE DATA TO THE SPECIFIED PORT 

MISCELLANEOUS REGISTER MOVE OPERATIONS 
XTHL iEXCHANGE TOP OF STACK WITH HL 

PCHL iPC RECEIVES THE HL VALUE 

SPHL iSP RECEIVES THE HL VALUE 

XCHG iEXCHANGE DE AND HL 

END OF INSTRUCTION LIST 

DS 2 5D0UBLE WORD TEMPORARY 

DS 2 iANOTHER TEMPORARY 

EQU H iLITERAL VALUE 

END 



Listing 5-4. Assembly Using Various Register/Memory Moves 
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5.5 Arithmetic Logic Unit Operations 

The 8080 set includes instructions that operate between the accumulator and sin- 
gle-precision registers, including operations on the A register and carry flag. The 
accumulator/register instructions are 



ADDe3 


ADCe3 


SUB e3 


SBB e3 


ANAe3 


XRAe3 


ORAe3 


CMPe3 



where e3 produces a value corresponding to one of the single-precision registers A, 
B, C, D, E, H, L, or M, where the M register is the memory location addressed by 
the HL register pair. 

The accumulator/carry operations given below operate upon the A register, or 
carry bit, or both. 

DAA CM A STC CMC 

RLC RRC RAL RAR 

The function of each instruction is listed in the comment line shown in Listing 5-5. 
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0000 


80 


0001 


8D 


0002 


9a 


0003 


99 


0004 


Al 


0005 


AF 


0006 


BO 


0007 


BC 


0008 


09 


0009 


27 


000A 


2F 


000B 


37 


oooc 


3F 


000D 


07 


000E 


OF 


000F 


17 


0010 


IF 



CP/M MACRO ASSEM 2.0 *001 ARITHMETIC LOGIC UNIT OPERATIONS 
TITLE 'ARITHMETIC LOGIC UNIT OPERATIONS' 



ASSUME OPERATION WITH ACCUMULATOR AND REGISTER* 
WHICH MUST PRODUCE At B, C» Dt E» H. L » OR M 



.ADD REGISTER TO A W/0 CARRY 
5ADD TO A WITH CARRY INCLUDED 
.SUBTRACT FROM A W/0 BORROW 
iSUBTRACT FROM A WITH BORROW 
iLOGICAL AND WITH REGISTER 
iLOGICAL XOR WITH REGISTER 
iLOGICAL OR WITH REGISTER 
iCOMPARE REGISTER* SETS FLAGS 



DOUBLE ADD CHANGES HL PAIR ONLY 

DAD B iDOUBLE ADD B,D,H,SP TO HL 

REMAINING OPERATIONS HAVE NO OPERANDS 

DAA iDECIMAL ADJUST REGISTER A USING LAST OP 

CMA '.COMPLEMENT THE BITS OF THE A REGISTER 

STC 5SET THE CARRY FLAG TO 1 

CMC iCOMPLEMENT THE CARRY FLAG 

RLC 58-BIT ACCUM ROTATE LEFT. AFFECTS CY 

RRC 58-BIT ACCUM ROTATE RIGHT* AFFECTS CY 

RAL 59-BIT CY/ACCUM ROTATE LEFT 

RAR 59-BIT CY/ACCUM ROTATE RIGHT 



ADD 


B 


ADC 


L 


SUB 


H 


SBB 


B + l 


ANA 


C 


XRA 


A 


ORA 


B 


CMP 


H 



0011 



END 



Listing 5-5. Assembly Showing ALU Operations 



The double-precision add instruction performs a 16-bit addition of a register pair 
(B, D, H, or SP) into the 16-bit value in the HL register pair. This addition produces 
the 16-bit (unsigned) sum of the two values. The sum is placed into the HL register 
pair. The form is 

DADe3 
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5.6 Control Instructions 

The four remaining instructions in the 8080 set are control instructions. These take 
the forms: 

HLT 
DI 
EI 
NOP 

They stop the processor (HLT), enable the interrupt system (EI), disable the interrupt 
system (DI), or perform a no-operation (NOP). 

End of Section S 
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Section 6 

An Introduction to 

Macro Facilities 



The fundamental difference between the Digital Research ASM and MAC assem- 
blers is that ASM provides only the facilities for assembling 8080 operation codes, 
and MAC includes a powerful macro processing facility. MAC implements the indus- 
try standard Intel macro definition, which includes the following pseudo operations. 

Macro definitions allow groups of instructions to be stored and substituted in the 
source program as the macro names are encountered. Definitions and macro calls 
can be nested; symbols can be constructed through concatenation using the special 
& operator, and locally defined symbols can be created using the LOCAL pseudo 
operation. Macro parameters can be formed to pass arbitrary strings of text to a 
specific macro for substitution during expansion. 

The MACLIB (macro library) feature allows the programmer to define a set of 
macros, equates, and sets and automatically includes them in a program. A macro 
library can contain an instruction set for another central processor that is not directly 
supported by the MAC built-in mnemonics. The macro library can also include 
general purpose input/output macros used in programs that operate in the CP/M 
environment to perform peripheral or disk I/O functions. 

IRPC, IRP, and REPT pseudo operations repeat source statements under control 
of a count or list of characters or items to be substituted each time the assembler 
rereads the statements. This feature is particularly useful in generating groups of 
assembly language statements with similar structure, such as a set of File Control 
Blocks where only the filetype is changed in each statement. 
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To illustrate the power of macro facility, consider the macro library shown in 
Listing 6-1, which resides in a disk file called MSGLIB.LIB. This macro library con- 
tains macro definitions that have standard instruction sequences for program startup, 
message typeout, and program termination. The program shown in Listing 6-2 pro- 
vides an example of the use of this macro library. The assembly shown in Listing 
6-2 lists both the macro calls and the statements in macro expansions that generate 
machine code. The statements marked by + in Listing 6-2 are generated from the 
macro calls. The remaining statements are a part of the calling program. 

The macro call 

ENTCCP 10 

in Listing 6-2 shows a specific expansion of ENTCCP (enter from CCP). ENTCCP is 
defined in Listing 6-1. The macro call causes MAC to retrieve the definition — the 
text between MACRO and ENDM in Listing 6-1 — and substitute this text following 
the macro call in Listing 6-2. Upon entry to the program from CCP, this macro saves 
the stack pointer (SP) into a variable called @ENTSP for later retrieval. The stack 
pointer is then reset to a local area for the remainder of the program execution. 

The size of the local stack is defined by the macro parameter named in the macro 
definition as SSIZE (see Listing 6-1), and filled in at the call with the value 10. The 
ENTCCP macro reserves space for a local stack of SSIZE =10 double bytes (2*10 
bytes) and, after setting up the stack, branches around this reserved area to continue 
the program execution. 
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SIMPLE MACRO LIBRARY FOR MESSAGE TYPEOUT 
iWARM START ENTRY POINT 
^TRANSIENT PROGRAM AREA 
iSYSTEM ENTRY POINT 
iWRITE CONSOLE CHARACTER FUNCTION 
5CARRIAGE RETURN 
!LINE FEED 



REBOOT 


EOU 


OOOOH 


TPA 


EOU 


0100H 


BDOS 


EOU 


0005H 


TYPE 


EOU 


? 


CR 


EOU 


ODH 


LF 


EOU 


OAH 



MACRO DEFINITIONS 



CHROUT MACRO 
MM I 
CALL 
ENDM 



CtTYPE 
BDOS 



iwrite a console character from register a 

;;type function 

i .'enter the bdos to write the character 



TYPEOUT 



MSGOUT: 



LOCAL 
JMP 

MOM 

MOM 

ORA 

RZ 

INX 

PUSH 

CHROUT 

POP 

JMP 



MACRO 7MESSAGE iTYPE LITERAL MESSAGE AT CONSOLE 

PASTSUB »;JUMP PAST SUBROUTINE INITIALLY 

PASTSUB 

;;this subroutine prints the message starting at hl 'til oo 



E»M 
A»E 
A 

H 
H 

H 
MSGOUT 



inext character to e 
;to accum to test for oo 

i = 00? 

iRETURN IF END OF MESSAGE 

.OTHERWISE MOME TO NEXT CHARACTER AND PRINT 

.SAME MESSAGE ADDRESS 

5 5RECALL MESSAGE ADDRESS 
liFOR ANOTHER CHARACTER 



PASTSUB: 



TYPEOUT 



TYMSG: 



PASTM: 



REDEFIN 

r 

LOCAL 

LOCAL 

LXI 

CALL 

JMP 

INCLUDE 

DB 

ARRIME 

ENDM 

TYPEOUT 

ENDM 



; .address the literal message 

?;call the premiously defined subroutine 



E THE TYPEOUT MACRO AFTER THE FIRST INVOCATION 

MACRO ??MESSAGE 

TYMSG JiLABEL THE LOCAL MESSAGE 

PASTM 

H»TYMSG 

MSGOUT 

PASTM 

THE LITERAL MESSAGE AT THIS POINT 

'FROM CONSOLE: &??MESSAGE ' ,CR »LF .0 
HERE TO CONTINUE THE MAINLINE CODE 

<?MESSAGE> 



Listing 6-1. A Sample Macro Library 
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ENTCCP 


MACRO 


SSIZE ; 


ENTER program from ccp. 




LOCAL 


START ! 


.AROUND THE STACK 




LXI 


H»0 






DAD 


sp . 


JSP VALUE IN HL 




SHLD 


HENTSP ; 


SENTRY SP 




LXI 


SP»iSTACK! 


5SET TO LOCAL STACK 




JMP 


START 






IF 


NUL SSIZE 






DS 


32 ; 


.DEFAULT 1G LEVEL STACK 




ELSE 








DS 


2*SSIZE 






ENDIF 






iSTACK 


: 


5 .LOW END 


OF STACK 


0ENTSP 


: 


DS 2 


5 5ENTRY SP 


START: 


ENDM 






RETCCP 


MACRO 


5RETURN TO 


CONSOLE PROCESSOR 




LHLD 


iENTSP 5 


.RELOAD CCP STACK 




SPHL 








RET 


5 


5BACK TO THE CCP 




ENDM 






ABORT 


MACRO 


;abort the 


PROGRAM 




JMP 


REBOOT 






ENDM 







END OF MACRO LIBRARY 



Listing 6-1. (continued) 
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CP/M MACRO ASSEM 2.0 001 SAMPLE MESSAGE OUTPUT MACRO 

TITLE 'SAMPLE MESSAGE OUTPUT MACRO' 







MACLIB 


MSGLIB ilNCLUDE THE MACRO LIBRARY 


0100 




ORG 


TPA iORIGIN AT THE TRANSIENT AREA 




! 


USE THE 


! MACRO LIBRARY TO TYPE TWO MESSAGES 






ENTCCP 


10 iENTER PROGRAM. RESERVE 10 LEVEL STACK 


0100+210000 




LXI 


H»0 


0103 + 39 




DAD 


SP 


0104+222101 




SHLD 


@ENTSP 


0107+312101 




LXI 


SP.0STACK 


010A+C32301 




JMP 


??0001 


010D + 




DS 


2*10 


0121 + 


0ENTSP: 




DS 2 






TYPE0U1 


" <THIS IS THE FIRST MESSAGE> 


0123+C33401 




JMP 


?'?0002 


012B+5E 




MOV 


E»M 


0127+B7 




ORA 


A 


0128 + CB 




RZ 




0129 + 23 




INX 


H 


012A + E5 




PUSH 


H 


012B+0E02 




MO I 


C.TYPE 


012D+CD0500 




CALL 


BDOS 


0130+E1 




POP 


H 


0131+C32B01 




JMP 


MSGOUT 


0134+213D01 




LXI 


H»??0003 


0137+CD2601 




CALL 


MSGOUT 


013A+C36701 




JMP 


??0004 


013D+46524F4D20 


??0003: 




DB 'FROM CONSOLE: THIS IS THE FIRST MESSAGE ' ,CR »LF .0 






TYPE0U1 


■ <THIS IS THE SECOND MESSAGE) 


01S7+217001 




LXI 


H»??0005 


01BA+CD2B01 




CALL 


MSGOUT 


016D+C39B01 




JMP 


??000S 


0170+4G524F4D20 


??0005: 




DB 'FROM CONSOLE: THIS IS THE SECOND MESSAGE ' ,CR »LF .0 






TYPE0U1 


■ <THIS IS THE THIRD MESSAGE) 


019B+21A401 




LXI 


H.??0007 


019E+CD2601 




CALL 


MSGOUT 


01A1+C3CE01 




JMP 


??0008 


01A4+4G524F4D20 


??0007: 




DB 'FROM CONSOLE: THIS IS THE THIRD MESSAGE ' ,CR »LF ,0 






RETCCP 


iRETURN TO THE CONSOLE COMMAND PROCESSOR 


01CE+2A2101 




LHLD 


@ENTSP 


01D1+F9 




SPHL 




01D2+C9 




RET 




01D3 




END 





Listing 6-2. A Sample Assembly Using the MACLIB Facility 
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Consider also the special macro statements used in Listing 6-1 within the body of 
the ENTCCP macro. The LOCAL statement defines the label START within the 
macro body. Each LOCAL statement causes the macro assembler to construct a 
unique symbol starting with ?? each time it is encountered. Thus, multiple macro 
calls reference unique labels that do not interfere with one another. ENTCCP also 
contains a conditional assembly statement that uses the NUL operator; this tests 
whether a macro parameter has been supplied or not. In this case, the ENTCCP 
macro can be started by 

ENTCCP 

with no actual parameter, resulting in a default stack size of 32 bytes. The following 
sections give exact details and examples. 

The TYPEOUT macro is a more complicated example of macro use. Note that this 
macro contains a redefinition of itself within the macro body. The structure of 
TYPEOUT is 



TYPEOUT 


MACRO 


?MESSAGE 


TYPEOUT 


♦ ♦ ♦ 

MACRO 
» ♦ ♦ 
ENDM 

♦ ♦ ♦ 
ENDM 


??MESSAGE 



where the outer definition of TYPEOUT completely encloses the inner definition. The 
outer definition is active upon the first invocation of TYPEOUT, but upon comple- 
tion, the nested inner definition becomes active. 

To see the use of such a nested structure, consider the TYPEOUT macro. Each 
time it starts, TYPEOUT prints the message sent as an actual parameter at the 
console device. The typeout process, however, can be easily handled with a short 
subroutine. Upon the first invocation, include the subroutine inline. Then simply call 
this subroutine on subsequent invocations of TYPEOUT. Thus, the outer definition 
of TYPEOUT defines the utility subroutine and then redefines itself, so that the 
subroutine is called, rather than including another copy of the utility subroutine. 
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Note that macro definitions are stored in the symbol table area of the assembler, 
so each macro reduces the remaining free space. MAC allows double semicolon 
comments to indicate that the comment itself is to be ignored and not stored with 
the macro. Thus, comments with a single semicolon are stored with the macro and 
appear in each expansion; comments with two preceding semicolons are listed only 
when the macro is defined. 

Listing 6-2 gives three examples of TYPEOUT invocations, with three messages 
that are sent as actual parameters. Note that the LOCAL statement causes a unique 
label to be created (??0002) in the place of PASTSUB, which is used to branch 
around the utility subroutine included inline between addresses 0126H and 0133H. 
The utility subroutine is then called, followed by another jump around the console 
message, also included inline. However, subsequent invocations of TYPEOUT use 
the previously included utility subroutine to type their messages. 

Although this example concentrates all macro definitions in a separate macro library, 
macros are often defined in the mainline (.ASM) source program. In fact, many 
programs that use macros do not use the external macro library facility at all. 

The rest of this manual examines many applications of macros. Macro facilities 
can simplify the programming task by abstracting from the primitive assembly lan- 
guage levels. That is, you can define macros that provide more generalized functions 
that are allowed at the pure assembly language level, such as macro languages for a 
given application, improved control facilities, and general purpose operating systems 
interfaces. The remainder of this manual first introduces the individual macro forms, 
and then presents several uses of the macro facilities in realistic applications. 



End of Section 6 
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Section 7 
Inline Macros 



The simplest macro facilities involve the REPT (repeat), IRPC (indefinite repeat 
character), and IRP (indefinite repeat) macro groups. All these forms cause the assem- 
bler to reread portions of the source program under control of a counter or list of 
textual substitutions. These groups are listed below in order of increasing complexity. 



7.1 The REPT-ENDM Group 

The REPT-ENDM group is written as a sequence of assembly language statements 
starting with the REPT pseudo operation and terminated by an ENDM pseudo oper- 
ation. The form is 

label: REPT expression 
statement- 1 
statement-2 

statement-n 
label: ENDM 

where the labels are optional. The expression following the REPT is evaluated as a 
16-bit unsigned count of the number of times that the assembler is to read and 
process statements 1 through n, enclosed within the group. 

Listing 7-1 shows an example of the use of the REPT group. In this case, the 
REPT-ENDM group generates a short table of the byte values 5, 4, 3, 2, and 1. 
Upon entry to the REPT, the value of NXTVAL is 5. This is taken as the repeat 
count, even though NXTVAL changes within the REPT. The macro lines that do not 
generate machine code are not listed in the repetition, while the lines that do generate 
code are listed with a + sign after the machine code address. Full macro tracing is 
optional, however, using assembly parameters. (See Section 10.) 
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CP/M MACRO ASSEM 2.0 



• 001 



SAMPLE REPT STATEMENT 



0100 



ORG 100H iBASE OF TRANSIENT AREA 

TITLE 'SAMPLE REPT STATEMENT' 

THIS PROGRAM READS INPUT PORT AND INDEXES 

INTO A TABLE 

BASED ON THIS VALUE. THE TABLE VALUE IS FETCHED 

AND SENT 

TO OUTPUT PORT 



0005 


= 


MAXVAL 


EQU 


5 


0100 


DBOO 


RLOOP: 


IN 





0102 


FE05 




CPI 


MAXVAL 


0104 


D20001 




JNC 


RLOOP 


0107 


211401 




LXI 


H»TABLE 


010A 


5F 




MOV 


EiA 


01 OB 


1600 




MVI 


DiO 


010D 


19 




DAD 


D 


010E 


7E 




MOV 


A»M 


01 OF 


D300 




OUT 





0111 


C30001 




JMP 


RLOOP 






i 
5 


GENERATE A TABL 


0005 


# 


NXTVAL 


SET 

TABLE: 

DB 


MAXVAL 

REPT 

NXTVAL 






NXTVAL 


SET 
ENDM 


NXTVAL- 


0114+05 




DB 


NXTVAL 


0115+04 




DB 


NXTVAL 


0116+03 




DB 


NXTVAL 


0117+02 




DB 


NXTVAL 


0118+01 




DB 


NXTVAL 


0119 






END 





LARGEST VALUE TO PROCESS 

READ THE PORT VALUE 

TOO LARGE? 

IGNORE INPUT IF INVALID 

ADDRESS BASE OF TABLE 

LOW ORDER INDEX TO E 

HIGH ORDER 00 FOR INDEX 

HL HAS ADDRESS OF ELEMENT 

FETCH TABLE VALUE FOR OUTPUT 

SEND TO THE OUTPUT PORT AND LOOP 

FOR ANOTHER INPUT 



iSTART COUNTER AT MAXVAL 
NXTVAL 

!FILL ONE (MORE) ELEMENT 
1 5 IAND DECREMENT FILL VALUE 

iFILL ONE (MORE) ELEMENT 

5FILL ONE (MORE) ELEMENT 

5FILL ONE (MORE) ELEMENT 

.FILL ONE (MORE) ELEMENT 

5FILL ONE (MORE) ELEMENT 



Listing 7-1. A Sample Program Using the REPT Group 



If a label appears on the REPT statement, its value is the first machine code 
address that follows. This REPT label is not reread on each repetition of the loop. 
The optional label on the ENDM is reread on each iteration; thus constant labels, 
not generated through concatenation or with the LOCAL pseudo operation, generate 
phase errors if the repetition count is greater than 1. 
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Properly nested macros, including REPTs, can occur within the body of the REPT- 
ENDM group. Further, nested conditional assembly statements are also allowed, 
with the added feature that conditionals beginning within the repeat group automat- 
ically terminate upon reaching the end of the macro expansion. Thus, IF and ELSE 
pseudo operations are not required to have their corresponding ENDIF when they 
begin within the repeat group, although the ENDIF is allowed. 



7.2 The IRPC-ENDM Group 

Similar to the REPT group, the IRPC-ENDM group causes the assembler to reread 
a bounded set of statements, taking the form: 

label: IRPC identifier,character-list 
statement- 1 
statement-2 

statement-n 
label: ENDM 

where the optional labels obey the same conventions as in the REPT-ENDM group. 
The identifier is any valid assembler name, not including embedded $ separators. 
Character list denotes a string of characters terminated by a delimiter (space, tab, 
end-of-line, or comment). 

The IRPC controls the reread process as follows: the statement sequence is read 
once for each character in the character list. On each repetition, a character is taken 
from the character list and associated with the controlling identifier, starting with the 
first and ending with the last character in the list. Thus, an IRPC header of the form 

IRPC ?X jABCDE 

rereads the statement sequence that follows (to the balancing ENDM) five times, 
once for each character in the list ABCDE. On the first iteration, the character A is 
associated with the identifier ?X. On the fifth iteration, the letter E is associated with 
the controlling identifier. 

On each iteration, the macro assembler substitutes any occurrence of the control- 
ling identifier by the associated character value. Using the preceding IRPC header, an 
occurrence of ?X in the bounds of the IRPC-ENDM group is replaced by the char- 
acter A on the first iteration, and by E on the last iteration. 
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The programmer can use the controlling identifier to construct new text strings 
within the body of the IRPC by using the special concatenation operator, denoted by 
an ampersand (6c) character. Again using the preceding IRPC header, the macro 
assembler replaces LAB&PX with LABA on the first iteration. LABE is produced on 
the final iteration. The concatenation feature is most often used to generate unique 
label names on each iteration of the IRPC reread process. 

The controlling identifier is not usually substituted within string quotes because 
the controlling identifier can appear as a part of a quoted message. Thus, the macro 
assembler performs substitution of the controlling identifier when it is preceded or 
followed by the ampersand operator. Further, all alphabetics outside string quotes 
are translated to upper-case, but no case translation occurs within string quotes. So 
the controlling identifier must not only be preceded or followed by the concatenation 
operator within strings, but it must also be typed in upper-case. 

Listings 7-2a and 7-2b illustrate the use of the IRPC-ENDM group. Listing 7-2a 
shows the original assembly language program, before processing by the macro 
assembler. The program is typed in both upper- and lower-case. Listing 7-2b shows 
the output from the macro assembler, with the lower-case alphabetics translated to 
upper-case. Three IRPC groups are shown in this example. The first IRPC uses the 
controlling identifier reg to generate a sequence of stack push operations that save 
the double-precision registers BC, DE, and HL. The lines generated by this group are 
marked by a + sign following the machine code address. 

construct a data table 

save relevant registers 
enter: irpc re*>bdh 

push res jisave res' 

en dm 
i 
5 initialize a partial ascii table 

irpc ctlAb*?@ 

data&c: db '&C 

en dm 
! 
5 restore registers 

i rpc res »hdb 

pop res 5!recall res 

endni 

ret 

end 

Listing 7-2a. Original (.ASM) File with IRPC Example 
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CONSTRUCT A DATA TABLE 






SAVE 


RELEVANT REGISTERS 




ENTER 


IRPC 
PUSH 
ENDM 




REG.BDH 

REG liSAVE REG 


0000+C5 




PUSH 




B 


0001+D5 




PUSH 




D 


0002+E5 




PUSH 




H 




i 
5 


INITIALIZE A PARTIAL ASCII T 






IRPC 




C»1AB*?@ 




DATA&C: DB 




'8.C 






ENDM 






0003+31 


DATA1 


DB 




'1' 


000/1+41 


DATAA 


DB 




'A' 


0005+42 


DATAB 


DB 




'B' 


0006+24 


DATA$ 


DB 




'$' 


0007+3F 


DATA? 


DB 




'? ' 


0008+40 


DATA@ 


DB 




'@' 




5 


RESTORE 


REGISTERS 






IRPC 




REG»HDB 






POP 




REG 5 5RECALL REG 






ENDM 






0009+E1 




POP 




H 


000A+D1 




POP 




D 


000B+C1 




POP 




B 


000C C9 




RET 






000D 




END 







Listing 7-2b. Resulting (.PRN) File with IRPC Example 



The second IRPC shown in Listing 7-2a uses the controlling identifier C to gener- 
ate a number of single-byte constants with corresponding labels. Although the con- 
trolling variable was typed in lower-case, it has been translated to upper-case during 
assembly. The string '&C occurs within the group and, because the controlling 
variable is enclosed in string quotes, it must occur next to an ampersand operator 
and be typed in upper-case for the substitution to occur properly. On each iteration 
of the IRPC, a label is constructed through concatenation, and a DB is generated 
with the corresponding character from the character list. 
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Substitution of the controlling identifier by its associated value can cause infinite 
substitution if the controlling identifier is the same as the character from the charac- 
ter list. For this reason, the macro assembler performs the substitution and then 
moves along to read the next segment of the program, rather than rereading the 
substituted text for another possible occurrence of the controlling identifier. Thus, an 
IRPC of the form 

IRPC C»1AC$?@ 
produces 

DATAC: DB 'C 

in place of the DB statement at the label DATAA in Listing 7-2b. 

The last IRPC restores the previously saved double-precision registers and performs 
the exact opposite function from the IPRC at the beginning of the program. 

When no characters follow the identifier portion of the IRPC header, the group of 
statements is read once, and the controlling identifier is deleted when it is read. It is 
replaced by the null string. 

7.3 The IRP-ENDM Group 

The IRP (indefinite repeat) functions like the IRPC, except that the controlling 
identifier can take on a multiple character value. The form of the IRP group is 

label: IRP identifier,K4cl-l,cl-2,...,cl-nl>2 
statement- 1 
statement-2 

statement-m 
label: ENDM 

where the optional labels obey the conventions of the REPT and IRPC groups. The 
identifier controls the iteration, as follows. On the first iteration, the character list 
given by cl-1 is substituted for the identifier wherever the identifier occurs in the 
bounded statement group (statements 1 through m). On the second iteration, cl-2 
becomes the value of the controlling identifier. Iteration continues in this manner 
until the last character list, denoted by cl-n, is encountered and processed. Substitu- 
tion of values for the controlling identifier is subject to the same rules as in the IRPC. 
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Note rules for substitution within strings and concatenation of text using the amper- 
sand &c operator. Controlling identifiers are always ignored within comments. 

Listing 7-3 gives several examples of IRP groups. The first occurrence of the IRP 
in Listing 7-3 is a typical use of this facility — to generate a jump vector at the 
beginning of a program or subroutine. The IRP assigns label names (INITIAL, GET, 
PUT, and FINIS) to the controlling identifier ?LAB and produces a jump instruction 
for each label by rereading the IRP group, substituting the actual label for the formal 
name on each iteration. 

The second occurrence of the IRP group in Listing 7-3 points out substitution 
conventions within strings for both IRPC and IRP groups. The controlling identifier 
IS takes on the values A-ROSE and ? on the two iterations of the IRP group, 
respectively. 

The controlling identifier is replaced by the character lists in the two occurrences 
of &IS and IS St inside the string quotes because they are both adjacent to the 
ampersand operator, is&c is not replaced because the controlling identifier is typed in 
lower-case, and there is no automatic translation to upper-case within strings. The 
occurrences of IS within the comments are not substituted. 

The last IRP group shows the effects of an empty character list. The value of the 
controlling identifier becomes the null string of symbols and, in the cases where ?X 
is replaced, produces the statement: 

DB ' ' 

DB produces no machine code and is therefore not listed in the macro expansion. 
The three statements 

DB '?x' DB '?)<' DB '6=' 

appear in the expansions because the '?x' is typed in lower-case and thus is not 
replaced. The '?X' does not appear next to an ampersand in the string and is thus 
not replaced. In the last case, only one of the double ampersands is absorbed in the 
'St&PX&t' string. Here, the two ampersands surrounding ?X are removed because 
they occur immediately next to the controlling identifier within the string. 
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Substitution rules outside of string quotes and comments are much less compli- 
cated; the controlling identifier is replaced by the current character-list value when- 
ever it occurs in any of the statements within the group. The ampersand operator 
can be placed before or after the controlling identifier to cause the preceding or 
following text to be concatenated. 

The actual forms for the character lists (cl-1 through cl-n) are more general than 
stated here. In particular, bracket nesting is allowed, and escape sequences allow 
delimiters to be ignored. The exact details of character list forms are discussed in the 
macro parameter sections. 
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CREATE A JUMP VECTOR USING THE IRP GROUP 







IRP 


?LAB»< INITIAL »GET .PUT »F INI S> 






JMP 


?LAB 5 5GENERATE THE NEXT JUMP 






ENDM 




0000+C30COO 




JMP 


INITIAL 


0003+C34300 




JMP 


GET 


000G+C34600 




JMP 


PUT 


0009+C34900 




JMP 


FINIS 




! 
! 


INDIVIDUAL CASES 




INITIAL 


: 




000C 211200 




LXI 


H.CHRS 


OOOF C35100 




JMP 


ENDCASE 




CHRS: 


IRP 


IS.<A-ROSE»?> 






DB 


'MS IS ISM ;is IS MS 






DB 


'MS isn''t isM 






ENDM 




0012+412D524F53 




DB 


'A-ROSE IS A-ROSE' 5IS IS MS 


0022+412D524F53 




DB 


'A-ROSE isrT't isM 


0032+3F20495320 




DB 


'? IS ?' !IS IS MS 


0038+3F20G973GE 




DB 


'? i sn "t isM 


0043 C35100 


5 

GET: 


JMP 


ENDCASE 


004G C35100 


i 

PUT: 


JMP 


ENDCASE 


0049 C35100 


i 
FINIS: 


JMP 


ENDCASE 






IRP 


?X»<> 






DB 


'?x' 






DB 


'?X' 






DB 


'MX' 






DB 


'MXM 






DB 


'8=MXM 






ENDM 




004C+3F78 




DB 


'?x' 


004E+3F5B 




DB 


'?X' 


0050+26 


ENDCASE 


DB 


'M 


0051 C9 




RET 




0052 




END 





Listing 7-3. A Sample Program Using IRP 
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7.4 The EXITM Statement 

The EXITM pseudo operation can occur within the body of a macro. Upon 
encountering the EXITM statement, the macro assembler aborts expansion of the 
current macro level. The EXITM pseudo operation occurs in the context 

macro-heading 
statement- 1 

label: EXITM 

statement-n 
ENDM 

where the label is optional, and macro-heading denotes the REPT, IRPC, or IRP 
group heading as described above. The EXITM statement can also be used with the 
MACRO group, as discussed in later sections. 

The EXITM statement usually occurs within the scope of a surrounding condi- 
tional assembly operation. If the EXITM occurs in the scope of a false conditional 
test, the statement is ignored, and macro expansion continues. If the EXITM occurs 
within the scope of a true conditional, the expansion stops where the EXITM is 
encountered. Assembly statement processing continues after the ENDM of the group 
aborted by the EXITM statement. 

Two examples of the EXITM statement are shown in Listing 7-4. This listing 
shows two IRPCs used to generate DB statements up to eight characters long. These 
IRPCs might occur within the context of another macro definition, such as in the 
generation of CP/M File Control Block (FCB) names. In both cases, the variable LEN 
counts the number of filled characters. If the count reaches eight characters, the 
EXITM statement is assembled under a true condition, and the IRPC stops expansion. 

The first IRPC generates the entire string SHORT because the length of the char- 
acter list is less than eight characters. Each evaluation of LEN = 8 produces a false 
value, and the EXITM is skipped. This IRPC terminates by exhausting the character 
list through its five repetitions. 

The second IRPC stops generation at the eighth character of the list LONG- 
STRING when the conditional LEN EQ 8 produces a true value, resulting in assem- 
bly of the EXITM statement. Note that = and EQ are equivalent operators. The 
EXITM causes immediate termination of the expansion process. 
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The second IRPC also contains a conditional assembly without the balancing ENDIF. 
In this case, the ENDIF is not required because the conditional assembly begins 
within the macro body. The ENDM serves the dual purpose of terminating unmatched 
IFs and marking the physical end of the macro body. 



0000 * 



0000+53 
0001+48 
0002+4F 
0003+52 
0004+54 



0000 » 



0005+4C 
0006+4F 
0007+4E 
0008+47 
0009+53 
000A+54 
000B+52 
000C+49 



LEN 



LEN 



LEN 



LEN 



SAMPLE USE OF THE EXITM STATEMENT WITH THE IRPC MACRO 

THE FOLLOWING IRPC FILLS AN AREA OF MEMORY WITH AT MOST 
EIGHT BYTES OF DATA: 



SET 

IRPC 

DB 

SET 

IF 

EXITM 

ENDIF 

ENDM 

DB 

DB 

DB 

DB 

DB 



INITIALIZE LENGTH TO 

N»SH0RT 

'&N' 

LEN + 1 

LEN = 8 

!ST0P MACRO IF AREA IS FULL 



'S' 
'H' 
'0' 
'R' 

'T 



THE FOLLOWING MACRO PERFORMS EXACTLY THE SAME FUNCTIONS AS 
SHOWN AB0UE. BUT ABORTS EXPANSION WHEN LENGTH EXCEEDS 8 



SET 


UNITIALIZE LENGTH COUNTER 


IRPC 


N.LONGSTRING 


DB 


'&N' 


SET 


LEN+1 


IF 


LEN EQ 8 


EXITM 




ENDM 




DB 


'L' 


DB 


'0' 


DB 


'N' 


DB 


'G' 


DB 


'S' 


DB 


'T' 


DB 


'R' 


DB 


'I' 



00 OD 



END 



Listing 7-4. Use of the EXITM Statement in Macro Processing 
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7.5 The LOCAL Statement 

It is often useful to generate labels for jumps or data references unique on each 
repetition of a macro. This facility is available through the LOCAL statement. The 
LOCAL statement takes the form: 

macro-heading 
label: LOCAL id-l,id-2,. . .,id-n 

ENDM 

where the label is optional, macro-heading is a REPT, IRPC, or IRP heading, already 
discussed, or a MACRO heading as discussed in following sections, and id-1 through 
id-n represent one or more assembly language identifiers that do not contain embed- 
ded $ separators. The LOCAL statement must occur within the body. It should 
appear immediately following the macro header to be compatible with the standard 
Intel macro facility. 

Upon encountering the LOCAL statement, the assembler creates a new frame of 
the form 

? ?nnnn 

for association with each identifier in the LOCAL list, where nnnn is a four-digit 
decimal value assigned in ascending order starting at 0001. Whenever the assembler 
encounters one of the identifiers in the list, the corresponding created name is substi- 
tuted in its place. Substitution occurs according to the same rules as those for the 
controlling identifier in the IRPC and IRP groups. 

Avoid the use of labels that begin with the two characters ??, so that no conflicting 
names accidentally occur. Symbols that begin with ?? are not usually included in the 
sorted symbol list at the end of assembly. (See Section 10 to override this default.) A 
total of 9999 LOCAL labels can be generated in any assembly. An overflow error 
occurs if more generations are attempted. 

Listing 7-5a shows an example of a program using the LOCAL statement to gen- 
erate both data references and jump addresses. This program uses the CP/M operat- 
ing system to print a series of four generated messages, as shown in the output from 
the program in Listing 7-5b. 
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The program begins with equates that define the operating system primary entry 
point, along with names for the nongraphic ASCII characters CR (carriage return) 
and LF (line-feed). The REPT statement that follows contains a LOCAL statement 
with the identifiers X and Y. These identifiers are used throughout the body of the 
REPT group. 

On the first iteration, X's value becomes ??0001, the first generated label; Y's value 
becomes ??0002. The substitution for X and Y within the generated strings follows 
the rules stated for controlling identifiers in previous sections. 
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Upon completion, four messages are generated along with four CALLs to the 
PRINT subroutine. At each call to PRINT, the message address is present in the DE 
register pair. The subroutine loads the print string function number into register C 
(C = 9) and calls the operating system to print the string value. 



0100 




ORG 


100H 


0005 = 


BDOS 


EOU 


5 


000D = 


CR 


EQU 


ODH 


O00A = 


LF 


EOU 


OAH 



'.BASE OF THE TRANSIENT AREA 
5BD0S ENTRY POINT 
.CARRIAGE RETURN (ASCII) 
iLINE FEED (ASCII) 



SAMPLE PROGRAM SHOWING THE USE OF 'LOCAL' 





REPT 


4 




LOCAL 


X»Y 




JMP 


Y 


X: 


DB 


'print x 


Y: 


LXI 


D.X 




CALL 


PRINT 




ENDM 




0100+C31E01 


JMP 


??0002 


0103+7072G96E74??0001 s 


DB 


'print x 


OllE+i 10301 ??0002: 


LXI 


D,??0001 


01Z1+CD9101 


CALL 


PRINT 


0124+C34201 


JMP 


??0004 


0127+7072696E74??0003: 


DB 


'print x 


0142+112701 ??0004: 


LXI 


D,??0003 


0ia5+CD9101 


CALL 


PRINT 


0148+C3GG01 


JMP 


??000G 


014B+7072G9GE74??0005: 


DB 


'print x 


01B6+1 14B01 ??000G: 


LXI 


D»??0005 


01B9+CD9101 


CALL 


PRINT 


01BC+C38A01 


JMP 


??0008 


016F+707269GE74??0007: 


DB 


'print x 


018A+11BF01 ??0008: 


LXI 


D,??0007 


018D+CD9101 


CALL 


PRINT 


0190 C9 


RET 




» 

0191 0E09 PRINT: 


MVI 


C,9 


0193 CD0500 


CALL 


BDOS 


019G C9 


RET 




0197 


END 





5REPEAT GENERATION 4 TIMES 
! .GENERATE TWO LABELS 
.JUMP PAST THE MESSAGE 
= &X» y = &Y' »CR»LF.'$' 
5READY PRINT STRING 



.JUMP PAST THE MESSAGE 
= ??0001 i y = ??0002' »CR»LF.'$' 
5READY PRINT STRING 

5JUMP PAST THE MESSAGE 
=??0003» y=??0004' >CR»LF»'$ 
5READY PRINT STRING 

.JUMP PAST THE MESSAGE 
=??0005» y=??000G' »CR»LF.'$' 
iREADY PRINT STRING 

.'JUMP PAST THE MESSAGE 
= ??0007» y = ??0008' .CR»LF>'$' 
5READY PRINT STRING 



Listing 7-5a. Assembly Program Using the LOCAL Statement 
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print x=??0001> y=??0002 

print x=??0003» y=??0004 

print x=??0005t y=??0006 

print x=??0007t y=??0008 



Listing 7-5b. Output from Program in Listing 7-5a 



Upon completion of the program, control returns to the Console Command Pro- 
cessor (CCP) for further operations. This program uses the default stack passed by 
the CCP. About 16 levels are available. This example is primarily intended to show 
operation of the LOCAL statement. Consult the CP/M documentation for BDOS 
interface conventions to follow this example completely. 



End of Section 7 
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Section 8 

Definition and Evaluation of 

Stored Macros 



The stored macro facility of MAC allows you to name a sequence of assembly 
language prototype statements to be included at selected places throughout the assembly 
process. Macro parameters can be supplied in various forms at the point of expan- 
sion which are substituted as the prototype statements are reread. These parameters 
tailor the macro expansion to a particular case. 

Although similar in concept to subroutine definition and call, macro processing is 
purely textual manipulation at assembly time. That is, macro definitions cause source 
text to be saved in the assembler's internal tables, and any expansion involves manip- 
ulating and rereading the saved text. 

You can combine macro features in various ways to greatly enhance the available 
facilities. Specifically, you can 

■ easily manipulate generalized data definitions 

■ define macros for generalized operating systems interface 

■ define simplified program control structures 

■ support nonstandard instruction sets, such as the Z80® 

Finally, well-designed macros for an application can achieve a measure of machine 
independence. 
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8.1 The MACRO-ENDM Group 

The prototype statements for a stored macro are given in the macro body enclosed 
by the MACRO and ENDM pseudo operations, taking the general form 

macname MACRO d-l,d-2,. . .,d-n 

statement- 1 
statement-2 

statement-m 
label: ENDM 

where the macname is any nonconflicting assembly language identifier; d-1 through 
d-n constitutes a (possibly empty) list of assembly identifiers without embedded $ 
separators, and statement- 1 through statement-m are the macro prototype state- 
ments. The identifiers denoted by d-1 through d-n are called dummy parameters for 
this macro. Although they must be unique within the macro body, dummy parame- 
ters can be identical to any program identifiers outside the macro body without 
causing a conflict. The prototype statements can contain any properly balanced assembly 
language statements or groups, including nested REPTs, IRPCs, MACROs, and IFs. 

The prototype statements are read and stored in the assembler's internal tables 
under the name give by macname. They are not processed until the macro is expanded. 
The following section gives the expansion process. 

The label preceding the ENDM is optional. 



8.2 Calling a Macro 

The macro text stored through a MACRO-ENDM group can be brought out for 
processing through a statement of the form 

label: macname a-l,a-2,. . .,a-n 

where the label is optional, and macname has previously occurred as the identifier 
on a MACRO heading. The actual parameters a-1 through a-n are sequences of 
characters separated by commas and terminated by a comment or end-of-line. 
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Upon recognition of the macname, the assembler first pairs off each dummy 
parameter in the MACRO heading (d-1 through d-n) with the actual parameter text 
(a-1 through a-n). The assembler associates the first dummy parameter with the first 
actual parameter (d-1 is paired with a-1), the second dummy with the second actual, 
and so forth until the list is exhausted. If more actuals are provided than dummy 
parameters, the extras are ignored. If fewer actuals are provided, then the extra 
dummy parameters are associated with the empty string (a text string of zero length). 
The value of a dummy parameter is not a numeric value, but is instead a textual 
value consisting of a sequence of zero or more ASCII characters. 

After each dummy parameter is assigned an actual textual value, the assembler 
rereads and processes the previously stored prototype statements and substitutes each 
occurrence of a dummy parameter by its associated actual textual value, according 
to the same rules as the controlling identifier in an IRPC or IRP group. 

Listings 8-1 and 8-2 provide examples of macro definitions and invocations. List- 
ing 8-1 begins with the definition of three macros, SAVE, RESTORE, and WCHAR. 
The SAVE macro contains prototype statements that save the principal CPU registers 
(PUSH PSW, B, D, and H). The RESTORE macro restores the principal registers 
(POP H, D, B, and PSW). The WCHAR macro contains the statements necessary to 
write a single character at the console using a CP/M BDOS call. 

The occurrence of the SAVE macro definition between MACRO and ENDM causes 
the assembler to read and save the PUSHs, but does not assemble the statements into 
the program. Similarly, the statements between the RESTORE MACRO and the 
corresponding ENDM are saved, as are the statements between the WCHAR MACRO 
and ENDM statements. The fact that the assembler is reading the macro definition is 
indicated by the blank columns in the leftmost 16 columns of the output listing. 
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Referring to Listing 8-1, note that machine code generation starts following the 
SAVE macro call. The prototype statements that were previously stored are reread 
and assembled, with a + between the machine code address and the generated code 
to indicate that the statements are being recalled and assembled from a macro defi- 
nition. The SAVE macro has no dummy parameters in the definition, so no actual 
parameters are required at the point of invocation. 

The SAVE call is immediately followed by an expansion of the WCHAR macro. 
The WCHAR macro, however, has one dummy parameter, called CHR, which is 
listed in the macro definition header. This dummy parameter represents the character 
to pass to the BDOS for printing. In the first expansion of the WCHAR macro, the 
actual parameter H becomes the textual value of the dummy parameter CHR. Thus, 
the WCHAR macro expands with a substitution of the dummy parameter CHR by 
the value H. The CHR is within string quotes, so it is typed in upper-case and 
preceded by the ampersand operator. Following the reference to WCHAR, the pro- 
totype statements are listed with the + sign to indicate that they are generated by 
the macro expansion. 
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0100 




ORG 


100H 


5BASE OF TRANSIENT AREA 


0005 = 


BDOS 


EOU 


5 


5BD0S ENTRY POINT 


0002 = 


CONOUT 


EOU 


? 


{CHARACTER OUT FUNCTION 




> 
SAME 


MACRO 

PUSH 

PUSH 

PUSH 

PUSH 

ENDM 


PSW 
B 
D 
H 


iSAME ALL CPU REGISTERS 




> 
RESTORE 


MACRO 

POP 

POP 

POP 

POP 

ENDM 


H 
D 
B 
PSW 


iRESTORE ALL REGISTERS 




WCHAR 


MACRO 


CHR 


5WRITE CHR TO CONSOLE 






MMI 


CtCONOUT 


! iCHAR OUT FUNCTION 






MMI 


E»'&CHR' 


i iCHAR TO SEND 






CALL 


BDOS 








ENDM 








1 

5 


MAIN PROGRAM STARTS HERE 






SAME 




5SAVE REGISTERS UPON ENTRY 


0100+F5 




PUSH 


PSW 




0101+C5 




PUSH 


B 




0102+D5 




PUSH 


D 




0103+E5 




PUSH 


H 








WCHAR 


H 


5SEND 'H' TO CONSOLE 


0104+0E02 




MMI 


CCONOUT 




0106+1E4B 




MM I 


E»'H' 




0108+CD0500 




CALL 


BDOS 








WCHAR 


I 


iSEND 'I ' TO CONSOLE 


010B+0E02 




MMI 


C .CONOUT 




010D+1E49 




MMI 


E.'I ' 




010F+CD0500 




CALL 
RESTORE 


BDOS 


IRESTORE CPU REGISTERS 


0112+E1 




POP 


H 




0113+D1 




POP 


D 




0114+C1 




POP 


B 




0115+F1 




POP 


PSW 




one cs 




RET 




5RETURN TO CCP 


0117 




END 







Listing 8-1. Example of Macro Definition and Invocation 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 69 



8.2 Calling a Macro Programmer's Utilities Guide 

The second invocation of WCHAR is similar to the first except that the dummy 
parameter CHR is assigned the textual value I, causing generation of a MVI E, T for 
this case. 

After the listing of the second WCHAR expansion, the RESTORE macro starts, 
causing generation of the POP statements to restore the register state. The RESTORE 
is followed by a RET to return to the CCP following the character output. 

This program saves the registers upon entry, typing the two characters HI at the 
console, restoring the registers, and then returning to the Console Command Proces- 
sor. The SAVE and RESTORE macros are used here for illustration and are not 
required for interface to the CCP, since all registers are assumed to be invalid upon 
return from a user program. Further, this program uses the CCP stack throughout. 
This stack is only eight levels deep. 

Listing 8-2 shows another macro for printing at the console. In this case, the 
PRINT macro uses the operating system call that prints the entire message starting at 
a particular address until the $ symbol is encountered. The PRINT macro has a 
slightly more complicated structure: two dummy parameters must be supplied in the 
invocation. The first parameter, called N, is a count of the number of carriage return 
line-feeds to send after the message is printed. The second parameter, called MES- 
SAGE, is the ASCII string to print that must be passed as a quoted string in the 
invocation. 

The LOCAL statement within the macro generates two labels denoted by PASTM 
and MSG. When the macro expands, substitutions occur for the two dummy para- 
meters by their associated actual textual values, and for PASTM and MSG by their 
sequentially generated label values. The macro definition contains prototype state- 
ments that branch past the message (to PASTM) that is included inline following the 
label MSG. The message is padded with N pairs of carriage return line-feed sequences, 
followed by the $ that marks the end of the message. The string address is then sent 
to the BDOS for printing at the console. 

Listing 8-2 includes two invocations of the PRINT macro. The invocation sends 
two actual parameters: the textual value 2 is associated with the dummy N, followed 
by a quoted string associated with the dummy parameter MSG. The second actual 
parameter includes the string quotes as a part of the textual value. The generated 
message is preceded by a jump instruction and followed by N = 2 carriage return 
line-feed pairs. 
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The second invocation of the PRINT macro is similar to the first, except that the 
REPT group is executed N = times, resulting in no carriage return line-feed pairs. 

Similar to Listing 8-1, the program of Listing 8-2 uses the Console Command 
Processor's eight-level stack for the BDOS calls. When the program executes, it types 
the two messages, separated by two lines, and returns to the CCP. 



0100 



ORG 



100H 



iBASE OF THE TPA 



0005 = 


BDOS 


EQU 


5 


iBDOS ENTRY POINT 


0009 = 


PMSG 


EQU 


9 


iPRINT 'TIL * FUNCTION 


000D = 


CR 


EQU 


0DH 


5CARRIAGE RETURN 


000A = 


LF 


EQU 


0AH 


5LINE FEED 



PRINT 



MACRO N. MESSAGE 

PRINT MESSAGE* FOLLOWED BY N CRLF'S 



LOCAL 


PASTM, 


.MSG 




JMP 


PASTM 


5 i JUMP PAST MSG 


MSG: 


DB 


MESSAGE 5 


5INCLUDE TEXT TO 


REPT 


N 


iiREPEAT 1 


DR LF SEQUENCE 


DB 


CR.LF 
ENDM 






DB 


'$' 


JiMESSAGE 


TERMINATOR 


PASTM: 


LXI 


D.MSG ; 


5MESSAGE ADDRESS 




MVI 


C.PMSG ; 


iPRINT FUNCTION 




CALL 


BDOS 






ENDM 






i 


PRINT 


2>'The rain in Spain 3oes' 


0100+C31E01 


JMP 


??0001 




0103+5468652072770002: 


DB 


'The rain 


in Spain Soes' 


0119+0D0A 


DB 


CR.LF 




011B+0D0A 


DB 


CR.LF 




011D+24 


DB 


'$' 




011E+110301 ??0001: 


LXI 


D.??00O2 




0121+0E09 


MVI 


C.PMSG 




0123+CD0500 


CALL 


BDOS 






PRINT 


> 'mainly 


down the d rain . ' 


0126+C34001 


JMP 


??0003 




0129+6D61696E6C??0004: 


DB 


'mainly d 


own the drain.' 


013F+24 


DB 


'$' 




0140+112901 ??0003: 


LXI 


D>??0004 




0143+0E09 


MVI 


C.PMSG 




0145+CD0500 


CALL 


BDOS 




0148 C9 


RET 







Listing 8-2. Sample Message Printout Macro 
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8.3 Testing Empty Parameters 

The NUL operator is specifically designed to allow testing of null parameters. Null 
parameters are actual parameters of length zero. NUL is used as a unary operator. 
NUL produces a true value if its argument is of length zero and a false value if the 
argument has a length greater than zero. Thus the operator appears in the context of 
an arithmetic expression as: 

. . . NUL argument 

where the ellipses (...) represent an optional prefixing arithmetic expression, and 
argument is the operand used in the NUL test. The NUL differs from other operators 
because it must appear as the last operator in the expression. This is because the 
NUL operator absorbs all remaining characters in the expression until the following 
comment or end-of-line is found. Thus, the expression 

X GT Y AND NUL XXX 

is valid because NUL absorbs the argument XXX, producing a false value in the scan 
for the end-of-line. The expression 

X GT Y AND NUL M +Z> 

is deceiving but nevertheless valid, even though it appears to be an unbalanced 
expression. In this case, the argument following the NUL operator is the entire 
sequence of characters M + Z). This sequence is absorbed by the NUL operator in 
scanning for the end-of-line. The value of NUL M + Z) is false because the sequence 
is not empty. 
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Listing 8-3 gives several examples of the use of NUL in a program. In the first 
case, NUL returns true because there is an empty argument following the operator. 
Thus, the true case is assembled, as indicated by the machine code to the left, and 
the false case is ignored. Similarly, the second use of NUL in Listing 8-3 produces a 
false value because the argument is nonempty. Both uses of NUL, however, are 
contrived examples, because NUL is only useful within a macro group, as shown in 
the definition of the NULMAC macro. 

NULMAC consists of a sequence of three conditional tests that demonstrate the 
use of NUL in checking empty parameters. In each of the tests, a DB is assembled if 
the argument is not empty and skipped otherwise. Seven invocations of NULMAC 
follow its definition, giving various combinations of empty and nonempty actual 
parameters. 

In the first case, NULMAC has no actual parameters. Thus all dummy parameters 
(A, B, and C) are assigned the empty sequence. As a result, all three conditional tests 
produce false results because both A and B are empty; B&C concatenates two empty 
sequences, producing an empty sequence as a result. 

The second invocation of NULMAC provides only one actual parameter, XXX, 
assigned to the dummy parameter A. B and C are both assigned the empty sequence. 
Thus only the DB for the first conditional test is assembled. 
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0000 7472756520 



0009 78787820G9 



NULMAC 



0017+B1203D2058 

0029+62203D2058 
003B+62G3203D20 

004F+612Q3D205B 
00G1+G2G3203D20 

0075+B2G3203D20 



0089+B263203D20 
009C 



IF 


NUL 


DB 


't rue case ' 


ELSE 




DB 


'false case ' 


ENDIF 




IF 


NUL XXX 


DB 


'xxx is nul ' 


ELSE 




DB 


'xxx is not nul' 


ENDIF 




MACRO 


A»B»C 


IF 


NOT NUL A 


DB 


'a = &A is not nul ' 


ENDIF 




IF 


NOT NUL B 


DB 


'b = &B is not nul ' 


ENDIF 




IF 


NOT NUL B8=C 


DB 


'be = &B&C is not nul 


ENDM 




NULMAC 




NULMAC 


XXX 


DB 


'a = XXX is not nul ' 


NULMAC 


>XXX 


DB 


'b = XXX is not nul' 


DB 


'be = XXX is not nul ' 


NULMAC 


XXX..YYY 


DB 


'a = XXX is not nul ' 


DB 


'be = YYY is not nul ' 


NULMAC 


»»YYY 


DB 


'be = YYY is not nul' 


NULMAC 


1 1 > 


NULMAC 


i ' ' t ' ' 


DB 


'be = '''' is not nul 


END 





Listing 8-3. Sample Program Using the NUL Operator 



The third case is similar to the second, except that the actual parameters for A and 
C are omitted. Thus, the second and third conditionals both test NOT NUL XXX, 
which is true because B has the value XXX, and B&C produces the value XXX as 
well. 
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The fourth invocation of NULMAC skips the actual parameter for B but supplies 
values for both A and C. Thus, the first and third test result in true values; the 
second conditional group is skipped. 

The fifth invocation provides an actual parameter only for C. As a result, only the 
third conditional is true because B&C produces the sequence YYY. 

The sixth invocation produces exactly the same result as the first because all three 
actual parameters are empty. 

The final expansion of NULMAC in Listing 8-3 shows a special case of the NUL 
operator. The expression 

NUL ' ' 

where the two apostrophes are in juxtaposition, produces the value true, even though 
there are two apostrophe symbols on the line following NUL and before the end-of- 
line. The value of A is the empty string in this case. The value assigned to both B 
and C consists of the two apostrophe characters side by side; this is treated as a 
quoted string of length zero, even though it is a sequence of two characters. In this 
last expansion, the first conditional, however, evaluates the form 

NOT NUL ' ' 

that is the special case of NUL applied to a length zero quoted string, but not a 
length zero sequence. Because of the special treatment of the length zero quoted 
string, this expression also produces a false result. The third conditional, however, 
must be considered carefully. The original expression in the macro definition takes 
the form 

NOT NUL B&C 

with B and C both associated with the sequence of length two given by two adjacent 
apostrophes. Thus, the macro assembler examines 

NOT NUL ' '&' ' 

or, after concatenation, 

NOT NUL 

where the four apostrophes are adjacent. Considering only the four apostrophes, the 
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macro assembler considers this a quoted string that happens to contain a single 
apostrophe because double apostrophes are always reduced to a single apostrophe. 
As a result, the test produces a true value, and the conditional segment is assembled. 
Usually the NUL operator is used only to test for missing arguments, as shown in 
later examples. (See Listing 8-6.) 

8.4 Nested Macro Definitions 

The MAC assembler allows you to include nested macro definitions. These take 
the form 



macl 


MACRO 


macl -list 


mac2 


MACRO 
ENDM 


mac2-list 



ENDM 

where macl is the identifier corresponding to the outer macro, and mac2 is an 
identifier corresponding to an inner nested macro that is wholly contained within the 
outer macro. In this case, macl-list and mac2-list correspond to the dummy parame- 
ter lists for macl and mac2, respectively. As before, labels are allowed on the ENDM 
statements. 

The statements contained within a macro definition are prototype statements that 
are read and stored by the assembler but not evaluated as assembly language state- 
ments until the macro is expanded. Thus, in the preceding form, only the macl 
macro is available for expansion because the assembler has stored but not processed 
the body of macl that contains the definition of mac2. mac2 cannot be expanded 
until macl is first expanded, revealing the definition of mac2. 

Properly balanced embedded macros of this form can be nested to any level, but 
they cannot be referenced until their encompassing macros have themselves been 
expanded. 
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Listing 8-4 gives a practical example of nested macro definition and expansion. 
This program writes characters either to the CP/M console device or to the currently 
assigned list device, according to the value of the LISTDEV flag set for the assembly. 
If the LISTDEV flag is true, then the assembly sends characters to the listing device. 
Otherwise, the console is used for output. In either case, the macro OUTPUT is 
produced; this sends a single character to the selected device. 

The sample program in Listing 8-4 uses the macro SETIO to construct the OUT- 
PUT macro. The OUTPUT macro is wholly contained within the SETIO macro and, 
as a result, remains undefined until SETIO is expanded. Upon encountering the invo- 
cation of SETIO, the macro assembler reads the prototype statements within SETIO 
and, in the process, constructs the definition of the OUTPUT macro. Because LIST- 
DEV is true for this assembly, the OUTPUT macro is defined as 

OUTPUT MACRO CHAR 

MM I E»CHAR 

MUI CLISTOUT 

CALL BDOS 
ENDM 

Note that the SETIO macro itself uses this newly created OUTPUT macro in its last 
prototype statement to print a single + at the selected device. 
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Following the invocation of SETIO, the invocations of OUTPUT are recognized 
because its definition has been entered in the process of reading the prototype state- 
ments of SETIO. These invocations send the characters 1 and 2 to the list device. 

0100 ORG 100H iBASE OF THE TPA 

0000 = FALSE EQU 0000H 5 VALUE OF FALSE 

FFFF = TRUE EQU NOT FALSE 5VALUE OF TRUE 

5 LISTDEU IS TRUE IF LIST DEVICE IS USED 

5 FOR OUTPUT. AND FALSE IF CONSOLE IS USED 
FFFF = LISTDEU EQU TRUE 



0005 = 


8D0S EQU 


5 


5BD0S ENTRY POINT 


0002 = 


C0N0UT EQU 


9 


.WRITE TO CONSOLE 


0005 = 


LIST0UT EQU 


5 


5WRITE TO LIST DEVICE 



SETIO MACRO iSETUP OUTPUT MACRO FOR LIST OR CONSOLE 



i .READY THE CHARACTER FOR PRINTING 



OUTPUT MACRO 


CHAR 




MVI 


E»CHAR ! 




IF 


LISTDEU 




MVI 


C.LISTOUT 




ELSE 






MVI 


C.CONOUT 




ENDIF 






CALL 


BDOS 




ENDM 






OUTPUT 


'# ' 




ENDM 




i 


SETIO 


5 


0100+1E2A 


MVI 


Ei'*' 


0102+0E05 


MVI 


CLISTOUT 


0104+CD0500 


CALL 


BDOS 




OUTPUT 


'1' 


0107+1E31 


MVI 


E»'l ' 


0109+0E05 


MVI 


C.LISTOUT 


010B+CD0500 


CALL 


BDOS 




OUTPUT 


'2' 


010E+1E32 


MVI 


E»'2' 


0110+OE05 


MVI 


C.LISTOUT 


0112+CD0500 


CALL 


BDOS 


0115 C9 


RET 




0116 


END 





iSETUP THE 10 SYSTEM 



Listing 8-4. Sample Program Showing a Nested Macro Definition 



78 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 8.5 Redefinition of Macros 

8.5 Redefinition of Macros 

It is often useful to redefine the prototype statements of a macro after the initial 
prototype statements have been entered. Redefinition is a specific instance of the 
nesting described in the previous section, where the inner nested macro carries the 
same name as the encompassing macro definition. Macro redefinition is extremely 
useful if the macro contains a subroutine. In this case, the subroutine can be included 
on the first expansion and simply called in any remaining expansions. Thus, if the 
macro is never invoked, the subroutine is not included in the program. 

Listing 8-5 shows an example of macro redefinition. This sample program defines 
the macro MOVE. MOVE is intended to move byte values from a starting source 
address to a target destination address for a particular number of bytes. The three 
dummy parameters denote these three values: SOURCE is the starting address; DEST 
is the destination address, and COUNT is the number of bytes to move (a constant 
in the range 0-65535). The actions of the MOVE macro, however, are complicated 
enough to be performed through a subroutine, rather than inline machine code each 
time MOVE is expanded. 

Examining the structure of MOVE in Listing 8-5, note that it contains a properly 
nested redefinition of MOVE, taking the general form: 

MOVE MACRO SOURCE,DEST,COUNT 

@MOVE subroutine 
MOVE MACRO ?S,?D,?C 
call to @MOVE 
ENDM 

invocation of MOVE 
ENDM 

Upon encountering the first invocation of MOVE, the assembler begins reading the 
prototype statements. Note, however, that the first expansion of the MOVE includes 
the subroutine for the actual move operation, labeled by @MOVE so that there is 
no name conflict (with a branch around the subroutine). MOVE then redefines itself 
as a sequence of statements that simply call the out-of-line subroutine each time it 
expands. The last statement of the original MOVE macro is an invocation of the 
newly defined version. As indicated by this example, once a macro has started expan- 
sion, it continues to completion (or until EXITM is assembled), even if it redefines 
itself. 
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0100 



ORG 100H iBASE OF TPA 
MOVE MACRO SOURCE .DEST .COUNT 
5 5 MOVE DATA FROM ADDRESS GIVEN BY 'SOURCE' 
5 5 TO ADDRESS GIVEN BY 'DEST' FOR 'COUNT' BYTES 

LOCAL PASTSUB 5 5LABEL AT END OF SUBROUTINE 



MOV 


A.C 


ORA 


B 


RZ 




MOV 


A.M 


STAX 


D 


INX 


H 


INX 


D 


DCX 


B 


JMP 


iMOVE 


PASTSUB: 




;; ARRIVE 


HERE ON F 


MOVE MACRO 


?S»?D.?C 


LXI 


H»?S 


LXI 


D.?D 


LXI 


B»?C 


CALL 


iMOVE 



JMP PASTSUB 5 5JUMP AROUND INLINE SUBROUTINE 
@MOVE: iJINLINE SUBROUTINE TO PERFORM MOVE OPERATION 
5 5 HL IS SOURCE. DE IS DEST. BC IS COUNT 

5L0W ORDER COUNT 
5ZER0 COUNT? 

5ST0P MOVE IF ZERO REMAINDER 
5GET NEXT SOURCE CHARACTER 
5PUT NEXT DEST CHARACTER 
5ADDRESS FOLLOWING SOURCE 
5ADDRESS FOLLOWING DEST 
5C0UNT=C0UNT-1 
5F0R ANOTHER BYTE TO MOVE 

FIRST INVOCATION - REDEFINE MOVE 
5 5CHANGE FARM NAMES 
5ADDRESS THE SOURCE STRING 
5ADDRESS THE DEST STRING 
5PREPARE THE COUNT 
iMOVE THE STRING 

ENDM 

CONTINUE HERE ON THE FIRST INVOCATION TO USE 

THE REDEFINED MACRO TO PERFORM THE FIRST MOVE 

MOVE SOURCE. DEST .COUNT 

ENDM 



Listing 8-5. Sample Program Showing Macro Redefinition 
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MOVE 


X1»X2»5 5M0VE 5 CHARS FROM XI TO X 


0100+C30E01 


JMP 


??0001 


0103+79 


MOV 


A»C 


0104+BO 


0RA 


B 


0105+CB 


RZ 




010B+7E 


MOV 


A»M 


0107+12 


STAX 


D 


0108+23 


INX 


H 


0109+13 


INX 


D 


010A+0B 


DCX 


B 


010B+C30301 


JMP 


@MOVE 


010E+212701 


LXI 


H.X1 


0111+114001 


LXI 


D.X2 


0114+010500 


LXI 


B.5 


0117+CD0301 


CALL 


iMOVE 




MOVE 


3000Htl000H»1500H 5BIG MOVER 


011A+210030 


LXI 


H»3000H 


011D+110010 


LXI 


D»1000H 


0120+010015 


LXI 


B»1500H 


0123+CD0301 


CALL 


iMOVE 


0126 C9 


RET 


iRETURN TO THE CCP 


0127 08G572G520X1: 


DB 


'here is some data to move' 


0140 7878787878X2: 


DB 


'xxxxxwe are ! ' 

Listing 8-5. (continued) 



It is important to note the use of ?S, ?D, and ?C in the previous example. The 
innermost MOVE macro uses the same sequence of three parameters for the source, 
destination, and count. The dummy parameter names must differ, however, because 
they would be substituted by their actual values if they were the same. This is 
because the inner MOVE macro is wholly contained within the outer macro, so 
parameter substitution takes place regardless of the context. 

Macro storage is not reclaimed upon definition, however, because the macro 
assembler performs two passes through the source program and saves any preceding 
definitions for the second pass scan. 
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8.6 Recursive Macro Invocation 

The prototype statements of a recursive macro x contain invocations of macros 
that, in turn, invoke macros that eventually lead back to an invocation of x. A direct 
recursion occurs when x invokes itself, as shown in the form below: 

macname MACRO d-l v . .,d-n 

macname a-1,. . .,a-n 

ENDM 

Although this form is similar to the embedded macro definition discussed in the 
previous section, macname is expanded within its own definition, rather than being 
redefined. Recursion is only useful, however, in the presence of conditional assembly 
where various tests are made that prevent infinite recursion. In fact, recursion is 
allowed only to sixteen levels before returning to complete the expansion of an 
earlier level. 

Listing 8-6 shows a situation in which indirect recursive macro invocation is use- 
ful. The macro WCHAR writes a character to the console device using the general 
purpose operating system macro CBDOS (call BDOS). CBDOS acts as an interface 
between the program and the CP/M system by performing the system function given 
by FUNC, with optional information address INFO. CBDOS loads the specified 
function to register C, then tests to see whether the INFO argument has been sup- 
plied, using the NUL operator. If supplied, INFO is loaded to the DE register pair. 
After register setup, the BDOS is called, and the macro has completed its expansion. 

Assume, however, that CBDOS has the additional task of inserting a carriage 
return line-feed before writing messages where operating system Function 9 (write 
buffer until $) has been specified. In this case, CBDOS uses the WCHAR macro to 
send the carriage return line-feed. The WCHAR macro, in turn, uses CBDOS to send 
the character, resulting in two activations of CBDOS at the same time. The assembler 
holds the initial invocation of CBDOS until the WCHAR macro has completed, then 
returns to complete the initial CBDOS expansion. 

In recursion the values of the dummy parameters are saved at each successive level 
of recursion and restored when that level of recursion is reinstated. Reentry into a 
macro expansion through recursion does not destroy the values of dummy arguments 
held by previous entry levels. 
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0100 




ORG 


1001 




! 


SAMPLE 


PROGI 


0005 = 


BD0S 


EOU 


000 


0002 = 


CDN0UT 


ECU 


2 


0009 = 


MSG0UT 


EOU 


9 


000D = 


CR 


EOU 


ODH 


000A = 


LF 


EOU 


OAH 



ibase of transient area 
program showing recursive macros 
;entry to bdos 
iconsole character out 
5print message 'til * 
5carriage return 

iLINE FEED 



WCHAR MACRO 



CHR 



WRITE THE CHARACTER CHR TO CONSOLE 
CBDOS CONOUTtCHR i iCALL BDOS 
ENDM 



0100+OE02 

0102+11G80( 

0105+CD050( 



CBDOS MACRO FUNCINFO 

5 5 GENERAL PURPOSE BDOS CALL MACRO 

ii FUNC IS THE FUNCTION NUMBER. 

;; INFO IS THE INFORMATION ADDRESS OR NUL 

!i CHECK FOR FUNCTION S> SEND CRLF FIRST IF SO 

IF FUNC=MSGOUT 
i ! PRINT CRLF FIRST 

WCHAR CR 

WCHAR LF 

END IF 
!5 NOW PERFORM THE FUNCTION 

MVI C.FUNC 
!! INCLUDE LXI TO DE IF INFO NOT EMPTY 
INFO 



IF 


NOT NUL 


LXI 


D»INFO 


ENDIF 




CALL 


BDOS 


ENDM 




WCHAR 


'h' 


MVI 


C.CONOUT 


LXI 


Dt'h' 


CALL 


BDOS 



iSEND ! "H" TO CONSOLE 



Listing 8-6. Sample Program Showing a Recursive Macro 
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WCHAR 


'i' .SEND 'I' TO CONSOLE 


0108+OE02 


MVI 


C.CONOUT 


010A+116900 


LXI 


D»'i' 


010D+CD0500 


CALL 


BDOS 




CBDOS 


MSGOUTtMSGADDR 5SEND MESSAGE 


0110+0E02 


MVI 


CtCONOUT 


0112+110D00 


LXI 


D»CR 


0115+CD0500 


CALL 


BDOS 


0118+0E02 


MO I 


CCONOUT 


011A+110A00 


LXI 


D.LF 


011D+CD0500 


CALL 


BDOS 


0120+0E09 


MVI 


CMSGOUT 


0122+112901 


LXI 


D »MSGADDR 


0125+CD0500 


CALL 


BDOS 


0128 C9 


RET 
! 

MSGADDR: 


TERMINATE PROGRAM 


0129 E1GEG42 


OGC DB 


'and lois$ ' 


0132 


END 





Listing 8-6. (continued) 



8.7 Parameter Evaluation Conventions 

You can exercise a number of options in the construction of actual parameters, 
and in the specification of character lists for the IRP group. Although an actual 
parameter is simply a sequence of characters placed between parameter delimiters, 
these options allow overrides where delimiter characters themselves become a part of 
the text. A parameter x occurs in the context: 



label: macname <. 



.> 



where macname is the name of a previously defined macro, and the preceding label 
is optional. The ellipses . . . represent optional surrounding actual parameters in the 
invocation of macname. In the case of an IRP group, the occurrence of a character 
list x is 

label: IRP id,. . ., x ,. . . 

where the label is again optional, and the ellipses represent optional surrounding 
character lists for substitution within the IRP group where the controlling identifier 
id is found. In either case, the statements can be contained within the scope of a 
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surrounding macro expansion. Hence, dummy parameter substitution can take place 
for the encompassing macro while the actual parameter is being scanned. 

The macro assembler follows the steps shown below in forming an actual parame- 
ter or character list: 

1. Leading blanks and tabs (control-I) are removed if they occur in front of x. 

2. The leading character of x is examined to determine the type of scan opera- 
tion to take place. 

3. If the leading character is a string quote (apostrophe), then x becomes the 
text up to and including the balancing string quote, using the normal string 
scanning rules: double apostrophes within the string are reduced to a single 
apostrophe, and upper-case dummy parameters adjacent to the ampersand 
symbol are substituted by the actual parameter values. Note that the string 
quotes on either end of the string are included in the actual parameter text. 

4. If the first character is the left angle bracket (<), then the bracket is removed, 
and the value of x becomes the sequence of characters up to, but not includ- 
ing, the balancing right angle bracket (>). The right angle bracket does not 
become a part of x. In this case, left and right angle brackets can be nested 
to any level within x, and only the outer brackets are removed in the evalu- 
ation. Quoted strings within the brackets are allowed, and substitution within 
these strings follows the rules stated in 3 above. Left and right brackets 
within quoted strings become a part of the string; these are not counted in 
the bracket nesting within x. Further, the delimiter characters comma, blank, 
semicolon, tab, and exclamation point become a part of x when they occur 
within the bracket nesting. 

5. If the leading character is a percent (%) character, then the sequence of 
characters that follows is taken as an expression that is evaluated immedi- 
ately as a 16-bit value. The resulting value is converted to a decimal number 
and treated as an ASCII sequence of digits, with left zero suppression (0- 
65535). 

6. If the leading character is not a quote, a left bracket, or a percent, the 
possibly empty sequence of characters that follows, up to the next comma, 
blank, tab, semicolon, or exclamation point, becomes the value of x. 
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There is one important exception to the preceding rules: the single-character escape, 
denoted by an up arrow, causes the macro assembler to read the special (nonalpha- 
betic) character immediately following as a part of x without treating the character 
as significant. The character following the up arrow, however, must be a blank, tab, 
or visible ASCII character. The up arrow itself can be represented by two up arrows 
in succession. If the up arrow directly precedes a dummy parameter, then the up 
arrow is removed, and the dummy parameter is not replaced by its actual parameter 
value. Thus, the up arrow can be used to prevent evaluation of dummy parameters 
within the macro body. Note that the up arrow has no special significance within 
string quotes and is simply included as a part of the string. 

Evaluation of dummy parameters in macro expansions has been presented throughout 
the previous sections. The macro assembler evaluates dummy parameters as follows: 

■ If a dummy parameter is either preceded or followed by the concatenation 
operator &, then the preceding or following & operator is removed, the 
actual parameter is substituted for the dummy parameter, and the implied 
delimiter is removed at the position where the ampersand occurs. 

■ Dummy parameters are replaced only once at each occurrence as the encom- 
passing macro expands. This prevents the infinite substitution that occurs if a 
dummy parameter evaluates to itself. 

In summary, parameter evaluation follows these rules: 

■ Leading and trailing tabs and blanks are removed. 

■ Quoted strings are passed with their string quotes intact. 

■ Nested brackets enclose arbitrary characters with delimiters. 

■ A leading percent symbol causes immediate numeric evaluation. 

■ An up arrow passes a special character as a literal value. 

■ An up arrow prevents evaluation of a dummy parameter. 

■ The & operator is removed next to a dummy parameter. 

■ Dummy parameters are replaced only once at each occurrence. 
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Listings 8-7, 8-8, and 8-9 show examples of macro definitions and invocations 
illustrating these points. In Listing 8-7, for example, two macros are defined, called 
MAC1 and MAC2. Each has several dummy parameters. In this case, the macro 
definitions are headed by DB statements to reveal the actual values passed in each 
case. There is a single mainline invocation of MAC2 with the actual parameters 



X+l » 1 



+ It ' K w o t e ' 



that associates I with E, the null sequence with F, the sequence X+l with G, the 
value 16 with H, and the literal string 'kwote' with S. MAC2 expands, filling the DB 
and MVI instructions with the substituted values. Before leaving MAC2, MAC1 is 
invoked with the value of E (the sequence I), the concatenation of the dummy argu- 
ment F with the sequence M (producing M since F's value is null), along with the 
literal value A, followed by the value of H (which is 16), and terminated by the value 
of S (yielding the string 'kwote'). These values are associated with MACl's dummy 
parameters. 



i MACRO PARAMETER EVALUATION 

i 

MAC1 MACRO A,B»C,D»S 

5 

5 ENTERING MACRO 1: 





DB 


'&A &=B &C 


&D 




DB 


S 




A: 


NOP 








MVI 


B»l 




til: 


NOP 






L&A&D: 


NOP 






! 


LEAVING 


MACRO 1 




» 


ENDM 






MAC2 


MACRO 


E»F>G)H»S 




i 


ENTERING MACRO 2: 






DB 


'iE &F &G 


&H 




DB 


S 






MVI 


MiH 






MAC1 


E,F&M»A,H 


»S 


5 


LEAVING 


MACRO 2 





ENDM 



Listing 8-7. Macro Parameter Evaluation Example 
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000F = X 


EQU 


15 


+ ; 
+ ; 


MAC2 


I ,, X+l , 1 X 


ENTERING MACRO 2: 


0000+492020582B 


DB 


'I X+l IB' 


0009+BB77GF7465 


DB 


'kwote ' 


000E+3610 


MVI 


M»16 


+ 

+ ; 
+ ; 


MAC1 


I »M»I >lG»'kwote ' 


ENTERING MACRO 1: 


0010+49204D2049 


DB 


'I M I IB' 


0018+6B77GF7465 


DB 


'kwote ' 


001D+00 I: 


NOP 




001E+3601 


MVI 


M,l 


0020+00 11: 


NOP 




0021+00 LI IS: 


NOP 




+ ; 

+ 5 

+ 


LEADING 


MACRO 1 


ENDM 




+ i 

+ 5 

+ 


LEAVING 


MACRO 2 


ENDM 




0022 


END 





kwote 



Listing 8-7. (continued) 



Upon expanding MAC1, the DB statements are filled out, followed by the substitu- 
tion of A as a label (producing A's value I). The MVI instruction references memory 
because B's value is M. Note that the concatenation of C with 1 reduces to a conca- 
tenation of A with 1 because C's value is A. The replacement of C by A constitutes 
a substitution of a single occurrence of a dummy parameter. Thus the A that is 
produced is not itself replaced at this point. Finally, the literal value L is concaten- 
ated to the value of A and D to produce the label LI 16. 

Listing 8-8 illustrates the use of bracketed notation, using IRPs (indefinite repeats) 
within three macros, called IRPM1, IRPM2, and IRPM3. Note that one bracket level 
is removed in the first invocation of IRPM1, leaving the IRP list with one bracket 
level (required in the IRP heading). Similarly, the IRPM2 invocation also eliminates 
the outer bracket level, but these brackets are replaced at the IRP heading within 
IRPM2. IRPM3 has three distinct dummy parameters that are reconstructed as a 
single list at the IRP heading it contains. IRPM4 shows the effect of passing parame- 
ters through two macro invocation levels by accepting a single parameter X, which 
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is immediately passed along to the IRPM1 macro. Note that the invocation requires 
three bracket levels: the first is removed at the nested invocation of IRPM1 inside 
IRPM4, and the innermost level is required at the IRP heading within IRPM1. 

Listing 8-9 presents various combinations of bracketed actual parameters, quoted 
strings, and escape sequences. The MAC1 macro has two parts: the first portion 
includes a DB statement showing the value of the first parameter X, if it is not empty, 
and the second part produces the value of Y, if not empty. Note that the first 
invocation includes a properly nested bracketed sequence for X and an empty param- 
eter for Y. The second invocation sends a properly nested bracketed expression for 
X that produces an empty value because no characters remain after the brackets are 
removed. The second parameter includes a quoted string ('string of pearls') and a 
hexidecimal value that becomes a part of the DB in MAC1. 

The third invocation of MAC1 passes a bracketed expression, including a quoted 
string (the pair of adjacent apostrophes), followed immediately by a sequence of 
ASCII characters. Note that the pair of apostrophes are passed intact because they 
appear as an empty quoted string. In this case, the value of Y is empty. The remain- 
ing examples show various cases of strings and escape sequences. Take care in pass- 
ing quoted strings that contain apostrophes because a pair of apostrophes is consid- 
ered a single apostrophe at each evaluation level in the sequence of macro invocations. 
Pay particular attention to the use of the escape character to pass an unevaluated 
dummy parameter from MAC2 to the MAC1 invocation. 





IRPM1 


MACRO 


X 




5 ? 


INDEFINITE REPEAT MACRO 






IRP 


Y>X 




Y: 


NOP 

ENDM 

ENDM 






J 


IRPM1 


<<0NEiTW0»THREE 


0000+00 


ONE: 


NOP 




0001+00 


TWO: 


NOP 




0002+00 


THREE: 


NOP 






> 
IRPM2 


MACRO 


X 






IRP 


Y»<X> 




Y: 


NOP 

ENDM 

ENDM 





Listing 8-8. Parameter Evaluation Using Bracketed Notation 
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0003+00 
0004+00 
0005+00 



FOUR: 
FIVE: 
SIX: 



IRPMi 

NOP 
NOP 
NOP 



<FOUR.FIME.SIX> 



IRPM3 



MACRO 

IRP 

NOP 

ENDM 

ENDM 



XI .X2.X3 
Y.<X1 ,X2»X3> 



OOOG+OO 
0007+00 
0008+00 



SEVEN: 
EIGHT: 
NINE: 



IRPM3 
NOP 
NOP 
NOP 



SEVEN. EIGHT. NINE 



IRPM4 



MACRO 
IRPMI 
ENDM 



0009+00 
OOOA+OO 
0005+00 
OOOC 



IRPM4 
TEN: NOP 
ELEVEN: NOP 
TWELVE: NOP 

END 



:TEN. ELEVEN. TWELVE>: 



Listing 8-8. (continued) 
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SAMPLE BRACKETED PARAMETERS* WITH ESCAPE CHARACTER 



MAC1 


MACRO 


X »Y 




DB 


'5:X' !(ONE) 




IF 


NUL Y 




EXITM 






ENDIF 






DB 


Y i(TWO) 




ENDM 




1 


MAC1 


<<LEFT SIDE) MIDDLE <RIGHT SIDE)) 


0000+3C4C454654 


DB 


'•(LEFT SIDE) MIDDLE <RIGHT SIDE)' 


i 


MAC1 


<> »< 'strinsf of p e a r 1 s ' » 34H ) 


001F+737472696E 


DB 


'strinsf of pearls't34H i(TWO) 


i 


MAC1 


<A QUOTE IS A " , RIGHT?) 


0030+41 205 1554F 


DB 


'A QUOTE ISA " , RIGHT?' 5(0NE) 


i 


MAC1 


<> #< ' risfht » but also '''''> 


004G+72B967S874 


DB 


' riaht * but also " ' 5 (TWO) 


1 


MAC1 


t < ' i s this 'f'''''confusinS'''''t6 


0057+6973207468 


DB 


'is this '»"'confusin3"'i63 i( 


1 


MAC1 


<HERE IS A ") AND A * 


00BB+4845524520 


DB 


'HERE IS A ) AND A A ' 5 (ONE) 


MAC2 


MACRO 


APARtBPAR 




LOCAL 


y s 


X 


EQU 


10 




DB 


APAR 




MAC1 


"APAR.BPAR 




ENDM 




J 


MAC2 


(X+5)*4 .'what ' ' ' ' ' ' "is J/oinsf on?' 


000 A+= ??0001 


EQU 


10 


007E+3C 


DB 


(??0001+5)#4 


007F+4 1504 152 


DB 


'APAR' !(ONE) 


0083+7768617427 


DB 


'what ' 's 5foin3 on?' \ (TWO) 



(ONE) 



63) 
(TWO) 



Listing 8-9. Examples of Macro Parameter Evaluation 



Examine the various parameters and their evaluations in Listing 8-9 to ensure that 
the rules for evaluation given in this section are consistent. 
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8.8 The MACLIB Statement 

The macro assembler allows you to create and reference macro library files that 
are external to the mainline program. The form of the macro library reference is 

MACLIB libname 

where libname is an identifier referencing file libname. LIB assumed to exist on the 
disk. Macro libraries are in source program form, so you can easily create and 
modify them using an editor program. 

In order to speed up the assembly process, macro libraries are read only on the 
first assembly pass. This places some restrictions on the use of the MACLIB state- 
ment, as listed below: 

■ The statements included in the macro library cannot generate machine code. 
For example, comments, EQUs, SETs, and MACRO definitions are allowed; 
DB statements outside macro definitions are not allowed. 

■ Macro libraries are not listed with the source program, although an overrid- 
ing parameter can be supplied. (See Section 10.) 

■ All MACLIB statements must appear before the mainline program macro 
definitions. The MACLIB statements are placed at the beginning of the pro- 
gram, followed by the mainline declarations and machine code. 

The principal advantage of the MACLIB feature is that you can predefine macros 
that enhance the facilities of the assembly language itself. For example, the additional 
operations codes of the Zilog Z80 microprocessor can be defined in a macro library 
that is referenced in a single statement 

MACLIB Z80 

causing the assembler to read the file Z80.LIB from the disk that contains the neces- 
sary macros for Z80 code generation. These macros can then be referenced within 
the program, intermixed with the usual 8080 mnemonics. 
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The libname.LIB file is assumed to exist on the currently logged disk drive. You 
can override this default condition using a special parameter (L) when the macro 
assembler is started that redirects the .LIB references to a different disk. (See Section 
10.) 

Listings 6-1 and 6-2 show the use of the macro library facility, as introduced in 
the initial macro discussion. The following sections contain additional examples of 
the use of MACLIB in practical applications. 

End of Section 8 
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Section 9 
Macro Applications 



The MAC assembler provides a powerful tool for microcomputer systems develop- 
ment through its macro facilities. To demonstrate this, the following sections describe 
a number of macro applications that solve practical problems in four applications 
areas: 

■ implementation of special purpose languages 

■ emulation of nonstandard machine architectures 

■ implementation of additional control structures 

■ operating systems interface macros 



9.1 Special Purpose Languages 

A wide variety of microcomputer designs can be broadly classed as controller 
applications. Specifically, the microcomputer is used as the controlling element in 
sequencing and decision making as real-time events are sampled and directed. 

Typical applications of this sort include assembly line sensing and control, metal 
machine control, data communications and terminal control functions, production 
instrumentation and testing, and traffic control systems. 

In many cases, application programmers set up the sequence of operations that the 
microprocessor carries out in performing its task. To avoid unnecessary details, the 
application programmer is not expected to know how to program and debug micro- 
computer assembly language programs. 

In this situation, it is useful to define a language through macros that suit the 
application. The application programmer uses these predefined macros as the primi- 
tive language elements. If properly defined, the application language is easily pro- 
grammed, allowing considerable machine independence. That is, an application pro- 
gram written for a particular microprocessor can be used with another processor by 
changing the definitions of the individual macros that implement the primitive oper- 
ations. Further, the macro bodies can incorporate debugging facilities for application 
development. 
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To illustrate language definition, consider the following situation. Hornblower 
Highway Systems, Inc. produces turnkey traffic control systems for cities throughout 
the country. Their hardware subsystems consist of various traffic lights and sensors 
customized for the traffic layout in a particular city. When Hornblower negotiates a 
contract, their engineers survey the intersections of the city and produce plans show- 
ing a configuration of their standard hardware for each intersection, along with the 
algorithms required for traffic flow at that point. 

The standard hardware items Hornblower manufactures consist of central and 
corner traffic lights that display green, yellow, and red (or off completely); pushbut- 
ton switches for pedestrian cross requests; road treadles for sensing the presence of 
an automobile at an intersection; and a central controller box. 

The central controller box contains an 8080 microcomputer connected through 
external logic to relays that control the lights and latches that hold the sensor input 
information. The controller box also contains a time of day clock that changes on an 
hourly basis from through 23. The 8080 processor in the controller box can be 
configured for any particular intersection with up to 1024 bytes of programmable 
Read-Only Memory (PROM) in 256-byte increments. Although Random Access 
Memory can be included in the controller box, Hornblower uses only ROM when 
possible. 

Thus, the Hornblower engineers examine the hardware requirements for each 
intersection in the city and produce hardware configuration plans that intermix the 
various standard components. Programs are then written and debugged that control 
each intersection, based on predicted traffic patterns. 
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The intersection of Easy Street and Maria Avenue, for example, controls minimal 
traffic and thus consists of a controller box with a single central light. The algorithm 
for this intersection simply alternates red and green lights between Easy and Maria, 
with a bias toward Easy Street because traffic along Easy has measured higher in the 
past surveys. Thus the green light along Easy lasts for 20 seconds, while the green 
along Maria lasts for only 15 seconds. Given this situation, the application program- 
mer writes the following program: 

HORNBLOWER HIGHWAYS SYSTEMS* INC. 
INTERSECTION: 

EASY STREET (N-S) / MARIA AUENUE(E-W) 



CYCLE 



MACLIB 


INTERSECT 


SETLITE 


NS»GREEN 


SETLITE 


EW tRED 


TIMER 


20 



CHANGE LIGHTS 
SETLITE NS»YELL0W 



5L0AD MACROS 



5 WAIT 20 SECS 



5WAIT 3 SECS 



5WAIT 15 SECS 



5WAIT 3 SECS 



The macro library INTERSECT. LIB contains the macro definitions that implement 
the primitive operations SETLITE and TIMER, setting the central traffic light and 
time out for the specified interval, respectively. Further, the RETRY macro causes 
the traffic light to recycle on each light change. The sequence of operations is easy to 
write and is completely machine independent. 



TIMER 


3 


SETLITE 


NS»RED 


SETLITE 


EW »GREEN 


TIMER 


15 


CHANGE BACK 


SETLITE 


EW »YELL0W 


TIMER 


3 


RETRY 


CYCLE 
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Listing 9-1 gives an example of a macro library for intersect that assumes the 
following hardware with an 8080 processor: the central traffic light is controlled by 
the 8080 output port (given by light); the time of day clock is read from port 3 
(clock). Further, the north-south (nsbits) of the central light are given by the high- 
order 4 bits of output port 0; the east- west direction (ewbits) is specified in the low- 
order 4 bits of output port 0. When either of these fields is set to 0, 1, 2, or 3, the 
light in that direction is turned off, or set to red, yellow, or green, respectively. Thus, 
the SETLITE macro in Listing 9-1 accepts a direction (NS or EW) along with a color 
(OFF, RED, YELLOW, or GREEN) and sets the specified direction to the appropri- 
ate color. 

macro library for basic intersection 

input/output ports for lisht and clocK 
lisht eiu OOh itraffic lisht control 
clocK eiu 03h !24 hour clocK <0»lt,,,»23) 
5 

5 constants for traffic lisht control 
nsbits e <=) u 4 5north south bits 
ewbits e q u ieast west bits 
5 

off equ »turn lisfht off 
red equ 1 Svalue for red liaht 
yellow equ 2 ivalue for yellow lisht 
Sreen eiu 3 Screen li^ht 
5 

setlite macro dirtcolor 

!5 set lisht 5"dir" (ns»ew) to 5 "color" (off»red>yellow»9'reen) 
mvi atcolor shl dir&bits 5 5 color readied 
out liaht 5 5 s en t in proper bit position 
endm 
5 

timer macro seconds 
ii construct inline time-out loop 

local tl»t2»t3 5 Sloop entries 

nds 55basic loop control 

> 5250msec *4 = 1 sec 

5 i 182*5. 5usec = 1msec 

5 51 cy = .5 usee 

i 5 + 10 cy = 5.5 usee 

i icount 250*249. . . 

Jiloop on b register 

5 ibasic loop cont rol 

5 5 loop on d register 



Listing 9-1. Macro Library for Basic Intersection 

98 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 





mui 


d»4*s 


tl: 


my i 


b »250 


t2: 


my i 


c »182 


t3: 


dc r 


c 




Jnz 


t3 




dc r 


b 




Jnz 


tz 




dc r 


d 




Jnz 


tl 
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55 arrive here with approximately !" seconds" sees timeout 

endrn 
5 

clock? macro low »hi 3h >if t rue 
55 Jump to !"iftrue" if clock is between low and hish 

local iffalse !5alternate to true case 

in clock 5 5 read real-time clock 

if not nul hish jjcheck hish clock 

cpi hish 5 Sexual or Greater? 

Jnc iffalse 55skip to end if so 

endif 

cpi low !51ess than low value? 

Jnc iftrue » 5 s K i p to label if not 



iffalse: 



endm 

macro sfolabel 

continue execution at 5 "So label" 

Jmp Solabel 

endm 



Listing 9-1. (continued) 



The TIMER macro in Listing 9-1 uses the internal cycle time of the 8080 processor 
to construct an inline timing loop, based on the value of SECONDS. This loop is not 
generated as a subroutine because Hornblower prefers not to include RAM in the 
controller box. (Subroutines require return addresses in RAM.) 

In addition to the basic intersection macro library, Hornblower has also defined 
macro libraries for all of the optional hardware components. Listing 9-2a, for exam- 
ple, is included when the intersection contains treadles in the street to detect auto- 
mobiles; Listing 9-2b shows the macro library for pedestrian pushbuttons. In the case 
of automotive treadles, the sensors are attached to input port 1 (trinp) of the proces- 
sor. The treadles, however, require a reset operation that clears the latched value 
through output port 1 (trout) of the controlling 8080 processor. In any particular 
intersection, the treadles are numbered clockwise from true north, labeled 0, 1, through 
a maximum of 7 treadles. Each sensor and reset position of the treadle ports corre- 
sponds to one bit position, numbered from the least to most significant bit. Thus the 
treadle #0 sensor is read from bit of port 1 and reset by setting bit of output 
port 1. Similarly, treadle #1 uses bit position 1 of input and output port 1. The 
TREAD? macro is invoked to sense the presence of a latched value for treadle tr and, 
if on, the sensor is reset, with control transferring to the label given by iftrue. 
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Listing 9-2b shows the macro library that processes pedestrian pushbuttons. Horn- 
blower's hardware senses the latched pedestrian switches on input port (cwinp) as 
a sequence of Is and Os in the least significant positions, corresponding to the switches 
at the intersection. Thus, if there are four pedestrian switches, bit positions 0, 1, 2, 
and 3 correspond to these switches. A 1 bit in any of these positions indicates that 
the pushbutton has been depressed. Unlike the automotive treadles, the crosswalk 
switch latches are all cleared whenever input port is read. Hornblower has defined 
several other libraries that support optional hardware manufactured by their company. 

5 macro library for street treadles 



t rinp 
t rout 



equ 
equ 



Olh 
Olh 



Jtreadle input port 
Jtreadle output port 



tread? macro tr»iftrue 

5 "tread?" is invoked to check if 
treadle Siven by tr has been sensed, 
if so t the latch is cleared and control 
transfers to the label 5"iftrue" 
local iffalse 55in case not set 



iffalse: 



endm 



trinp 55read treadle switches 

5mask proper bit 
!skip reset if 
5to reset the bit 
5c 1 ea r it 
!So to true label 



ani 


1 shl tr 


Jz 


iffalse 


mvi 


a > 1 shl tr 


out 


t rut 


Jhip 


if t rue 



Listing 9-2a. Macro Library for Treadle Control 



5 macro library for pedestrian pushbuttons 

5 

cwinp e=iu OOh iinput port for crosswalk 

5 

push? macro iftrue 

i"push?" Jumps to label 5"iftrue" when any one 
of the crosswalk switches is depressed. The 
value has been latched, and reading the port 
clears the latched values 

in cwinp !!read the crosswalk switches 
ani (1 shl cwcnt) - 1 !5build mask 
jnz iftrue 55any switches set? 
continue on false condition 
endm 

Listing 9-2b. Macro Library for Corner Pushbuttons 
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The intersection of Bumpenram Boulevard and Lullabye Lane presents a more 
complicated situation. Bumpenram carries heavy traffic in an E-W direction to and 
from the center of town. Lullabye, however, feeds a residential portion of the city, 
running perpendicular to Bumpenram in a N-S direction. The contracting city wants 
the traffic control biased toward Bumpenram as follows: the traffic light must remain 
green along Bumpenram until the treadles along Lullabye detect the presence of 
automobiles or until the pedestrian switches are pushed. At that time, the light must 
change to allow the traffic to move N-S through Lullabye, allowing all traffic to clear 
before returning to the major E-W flow along Bumpenram. Late night traffic along 
Bumpenram is not very heavy, so the city also wants the E-W light to flash yellow 
and the N-S direction to flash red between the hours of 2 and 5 a.m. 

The application program created by Hornblower for the Bumpenram and Lullabye 
intersection is shown in Listings 9-3a, 9-3b, and 9-3c. Each major cycle of the traffic 
light enters at CYCLE where the time of day is tested. Between 2 and 5 a.m., control 
transfers to NIGHT where the yellow and red lights are flashed in the appropriate 
directions. During other hours, the switches and treadles are sampled until N-S traffic 
along Lullabye is sensed. If cross traffic is detected, the lights switch until all the 
traffic is through. Sampling also stops when the time of day reaches 2 a.m. 

Listing 9-3 a shows the assembly with no macro generated lines, controlled by the 
-M parameter. (See Section 10.) Although the machine code locations are shown to 
the left, no 8080 machine code is listed. Listing 9-3b shows a segment of this same 
program with machine code generation, but no 8080 mnemonics, controlled by *M. 
Listing 9-3 a is the most readable to the application programmer. Listings 9-3 b and 
9-3c are useful for macro debugging. 

Note that the resulting program requires no RAM for execution because all tem- 
porary values are maintained in the 8080 registers. Further, the program is less than 
256 bytes, so it can be placed in a single programmable Read-Only memory chip for 
a minimum memory/processor configuration. 
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INTERSECTION: BUMPENRAM BLVD / LULLABYE LN. 



0004 
0000 
0001 



0000 



000C 
0010 



CWCNT EOU a 
LULLO EQU 
LULL1 EOU 1 



MACLIB INTER 
MACLIB TREADLES 
MACLIB BUTTONS 



iSET TO 4 CROSSWALK SWITCHES 
.NAME FOR TREADLE ZERO 
5NAME FOR TREADLE ONE 

.BASIC INTERSECTION 
.INCLUDE TREADLES 
i INCLUDE PUSHBUTTONS 



CYCLE: iENTER HERE ON EACH MAJOR CYCLE OF THE LIGHT 



CLOCK? 2. 5 .NIGHT 
iNOT BETWEEN 2 AND 5 AM 
SETLITE NS.RED 
SETLITE EW. GREEN 



iSPECIAL FLASHING? 



5RED LIGHT ON LULLABYE 
iGREEN ON BUMPENRAM 



0014 
001B 
0029 
0037 
003E 



0041 
0045 
0057 
005B 
005F 



0071 
007F 



008D 



SAMPLE: .SAMPLE THE BUTTONS AND TREADLES 
PUSH? SWITCH 5ANY0NE THERE? 
TREAD? LULLO .SWITCH .TREADLE 0? 
TREAD? LULL1. SWITCH .TREADLE 1? 
CLOCK? 2.. NIGHT .PAST 2AM? 
RETRY SAMPLE iTRY AGAIN IF NOT 

SWITCH: 

5S0ME0NE IS WAITING. CHANGE LIGHTS 

SETLITE EW. YELLOW .'SLOW 'EM DOWN 

TIMER 3 -WAIT 3 SECONDS 

SETLITE EW.RED .STOP 'EM 

SETLITE NS .GREEN 5LET 'EM GO 

TIMER 23 5F0R AWHILE 

DONE?: US ALL THE TRAFFIC THROUGH ON LULLABYE? 
TREAD? LULLO. NOTDONE .TREADLE 0? 
TREAD? LULL1 .NOTDONE 5TREADLE 1? 
5NEITHER TREADLE IS SET. CYCLE 
RETRY CYCLE 5F0R ANOTHER LOOP 





NOTDONE 


: 




0090 




TIMER 5 


.WAIT 5 SECONDS 


00A2 




RETRY DONE? 


iTRY AGAIN 




NIGHT: 


5THIS IS NIGHTTIME. 


FLASH LIGHTS 


00A5 




SETLITE EW.OFF 


5TURN OFF 


00A9 




SETLITE NS.OFF 


.TURN OFF 


OOAD 




TIMER 1 


5WAIT WITH OFF 


OOBF 




SETLITE EW. YELLOW 


.TURN TO YELLOW 


00C3 




SETLITE NS.RED 


;turn to red 


00C7 




TIMER 1 


.LEAVE ON FOR 1 SEC 


00D9 




RETRY CYCLE 


5G0 AROUND AGAIN 
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0000+DB03 

000Z+FE05 

0004+D20C00 

0007+FE02 

0009+D2A500 



000C+3E10 
OOOE+D300 



0010+3E03 
0012+D300 



0014+DB00 
001B+EB0F 
0018+024100 

001B+DB01 

001D+EG01 

001F+CA2900 

0022+3E01 

0024+D301 

0026+C34100 

0029+DB01 

002B+E602 

002D+CA3700 

0030+3E02 

0032+D301 

0034+C34100 

0037+DB03 
0039+FE02 
003B+D2A500 

003E+C31400 



INTERSECTION: BUMPENRAM BLVD / LULLABYE LN, 



iSET TO 4 CROSSWALK SWITCHES 
iNAME FOR TREADLE ZERO 
!NAME FOR TREADLE ONE 

iBASIC INTERSECTION 
UNCLUDE TREADLES 
i INCLUDE PUSHBUTTONS 



CYCLE: .ENTER HERE ON EACH MAJOR CYCLE OF THE LIGHT 
CLOCK? 2.5 .NIGHT iSPECIAL FLASHING? 



0004 = 


CWCNT 


EOU 4 


0000 = 


LULLO 


EOU 


0001 = 


LULL1 


EOU 1 




MACLIB 


INTER 




MACLIB 


TREADLES 




MACLIB 


BUTTONS 



!NOT BETWEEN 2 AND 5 AM 

SETLITE NS.RED 5RED LIGHT ON LULLABYE 



SETLITE EN .GREEN 



iGREEN ON BUMPENRAM 



SAMPLE: iSAMPLE THE BUTTONS AND TREADLES 
PUSH? SWITCH .ANYONE THERE? 



TREAD? LULLO. SWITCH 5TREADLE 0? 



TREAD? LULL1 .SWITCH iTREADLE 1? 



CLOCK? 2.. NIGHT 



RETRY SAMPLE 



iPAST 2 AM? 



iTRY AGAIN IF NOT 



Listing 9-3b. Intersection Algorithm with *M in Effect 
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SWITCH: 







.SOMEONE IS WAITING. CHANGE LIGHTS 






SETLITE 


EW. YELLOW 


iSLOW 'EM DOWN 


0041+3E02 




MVI 


A. YELLOW SHL EWBITS 


OO43+D30O 




OUT 


LIGHT 








TIMER 


3 


5WAIT 3 SECONDS 


0045+160C 




mvi 


D»4*3 




0047+06FA 


??0005: 


MVI 


B.250 




0049+0EB6 


??000G: 


MVI 


C.182 




004B+0D 


??0007: 


DCR 


C 




004C+C24B00 




JNZ 


??0007 




004F+05 




DCR 


B 




0050+C24900 




JNZ 


??00OG 




0053+15 




DCR 


D 




0054+C24700 




JNZ 


??0005 








SETLITE 


EW.RED 


iSTOP 'EM 


0057+3E01 




MVI 


A. RED SHL EWBITS 




OO59+D30O 




OUT 


LIGHT 








SETLITE 


NS. GREEN 


iLET 'EM GO 


005B+3E30 




MVI 


A.GREEN SHL NSBITS 


005D+D300 




OUT 


LIGHT 








TIMER 


23 


5F0R AWHILE 


005F+165C 




mvi 


D.4*23 




0061+06FA 


??0008: 


mi 


B.250 




0063+03BB 


??0009: 


mi 


C.182 




0OG5+OD 


??0010: 


DCR 


C 




00GG+C26500 




JNZ 


??0010 




00G9+05 




DCR 


B 




OOGA+C2G300 




JNZ 


??0009 




006D+15 




DCR 


D 




006E+C2G100 




JNZ 


??O0OB 






DONE?: 


5IS ALL 


THE TRAFFIC THROUGH ON LULLABYE? 






TREAD? 


LULLO.NOTDONE 


iTREADLE 0? 


0071+DB01 




IN 


TRINP 




0073+EG01 




ANI 


1 SHL LULLO 




0075+CA7FO0 




JZ 


??0011 




0078+D301 




mi 


A.l SHL LULLO 




OO7A+D301 




OUT 


TROUT 




007C+C39000 




JMP 


NOTDONE 








TREAD? 


LULL1 .NOTDONE 


5TREADLE 1? 


007F+DB01 




IN 


TRINP 




0081+E602 




ANI 


1 SHL LULL1 




0083+CA8DO0 




JZ 


??0012 




008G+3E02 




MVI 


A.l SHL LULL1 




0088+D301 




OUT 


TROUT 




008A+C39000 




JMP 


NOTDONE 








5NEITHER TREADLE IS SET. 


CYCLE 






RETRY 


CYCLE 


5F0R ANOTHER LOO 


008D+C30000 




JMP 


CYCLE 





Listing 9-3c. Algorithm with Generated Instructions 
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Macro-based languages of this sort can easily incorporate debugging facilities. In 
the case of Hornblower, Inc., the principal algorithms are constructed and tested in 
the CP/M environment by including debugging traces within each macro. In each 
case, a debug flag is tested and, if true, machine code is generated to trace the 
operation at the console, rather than actually executing the input/output calls. 

Listing 9-4 shows the modification required to the INTER.LIB file to include the 
debugging code. Although only the SETLITE macro is shown, similar coding is easily 
included for the remaining macros. Listing 9-4 includes the debug flag at the begin- 
ning of the library, initially set to FALSE, along with the appropriate equates for 
CP/M system calls. If the debug flag is set to true by the application programmer, 
special trace calls are included. For example, the setlite macro constructs a message 
of the form 

DIR changing to COLOR 

where DIR and COLOR are the parameters sent to the macro. If debug remains false 
in the application program, this trace code is not assembled. 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 105 



9.1 Special Purpose Languages 



Programmer's Utilities Guide 



macro library for basic intersection 



t rue 

false 

debus 

bdos 

rchar 

wbuf f 

cr 

If 



jflobal definitions for debus processing 

equ Offffh 

equ not true 

set false 

equ 5 

eiu 1 

equ 9 

equ Odh 

equ Oah 



value of true 
value of false 
initially false 
entry to cp/m bdos 
read character function 
write buffer function 
carriage return 
line feed 



5 input/output ports for lisht and clocK 

lisht equ OOh 5 1 raff ic lisht control 

clock equ 03h 524 hour clock (0»1»,..»23) 

5 

5 bit positions for traffic lisht control 

nsbits equ 4 Jnorth south bits 

ewbits equ ieast west bits 

5 

5 constant values for the lisht control 

off equ Uurn lisht off 

red equ 1 ivalueforredlisht 

yellow equ 2 ivalue for yellow lisht 

Sreen equ 3 53reen liflht 



setl ite mac r di r >colo r 

55 set 1 i 3 h t siven by "dir" to color tfiven by 

if debus iiprint info at console 

local setwsS tpastwss 

mvi c»wbuff 55write buffer function 

lxi d >setmsS 

call bdos iiwrite the trace info 

Jmp pastMss 

db cr »lf 

db '&DIR chanSin* to &COLOR$ ' 



setins i : 
pastms 3 



exittn 

endif 

iflvi 

out 

endm 



'color' 



a>color shl dir&bits readied 
lisht jisent in proper bit position 



(remaining macros are identical to the previous figure, 
but each contains trace information similar to "setlite") 



Listing 9-4. Library Segment with Debug Facility 
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Listing 9-5 a shows an application program for an intersection where the debug 
flag is set to TRUE after the macro library is included. As a result, each macro 
expansion assembles a call to the CP/M operating system to trace the light direction 
and color change, skipping the machine code that is eventually assembled to drive 
the actual Hornblower hardware. 

The application programmer then uses CP/M to trace the operation of the algo- 
rithm, resulting in the printout shown in Listing 9-5 b. Each trace line corresponds to 
a SETLITE call with a specific direction and color, with the appropriate wait time 
between printouts. 



0100 

FFFF* 

0100 
0120 
0142 
0154 
0177 
1089 
01A9 
01CB 
01DD 
0200 
0212 



DEBUG 



CYCLE: 



ORG 


100H 5READY 


FOR THE DEBUG RUN 


MACLIB 


INTER 5BASIC 


MACRO LIBRARY 


SET 


TRUE iREADY 


DEBUG TOGGLE 


SETLITE 


NStRED 




SETLITE 


EW .GREEN 




TIMER 


10 




SETLITE 


EW»YELL0W 




TIMER 


2 




SETLITE 


EW.RED 




SETLITE 


NS.GREEN 




TIMER 


10 




SETLITE 


NS. YELLOW 




TIMER 


2 




RETRY 


CYCLE 





Listing 9-5 a. Sample Intersection Program with Debug 



NS 


chansinS 


to 


RED 


EW 


chain 3 in 3 


to 


GREEN 


EW 


chanSinS 


to 


YELLOW 


EW 


chansin 


to 


RED 


NS 


chansinS 


to 


GREEN 


NS 


chanSin i 


to 


YELLOW 


NS 


chansinS 


to 


RED 


EW 


chantfinS 


to 


GREEN 


EW 


chansin i 


to 


YELLOW 


EW 


chanSinS 


to 


RED 



Listing 9-5b. Debug Trace Printout 
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Upon completion of the initial debugging under CP/M, the SET statement in the 
application program is removed — the ORG can be removed as well — and the pro- 
gram is reassembled. This time, the CP/M traces are not included because the debug 
flag remains FALSE. As a result, the actual Hornblower hardware interface is assem- 
bled instead. The newly assembled program is then placed into PROM in the con- 
troller box for that intersection and tested in its target environment. 

This approach to macro based language facilities provides a simple tool for rapid 
development and debugging of programs where high-level languages are not avail- 
able, but a measure of machine independence is required. The macros are easy to 
develop, and the application programs are simple to write and debug. 



9.2 Machine Emulation 

A second application of macro processing is in the emulation of a machine opera- 
tion code set that is different from the 8080 microprocessor. In particular, a machine 
architecture is selected, based on an existing or fictitious operation code set, and a 
macro is written for each opcode, taking the general form: 

op MACRO d-l,d-2 v . .,d-n 
opcode emulation 
ENDM 

where op is a mnemonic instruction in the emulated machine, and the dummy 
parameters d-1 through d-n represent the optional operands required by op. The 
macro body includes 8080 instructions that carry out the operation on the 8080 
microprocessor. This means the instructions within the macro body perform the same 
function as the op with its arguments on the emulated machine. 

Upon completion of the opcode macro definitions, a program can be written using 
these opcodes. These opcodes expand to the equivalent 8080 instructions but per- 
form the emulated machine operations. 
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For example, consider the situation encountered by Nachtflieger Maschinewerke, 
an internationally famous manufacturer and distributor of automated machining 
equipment. Though incorporating microprocessors in controlling their equipment, 
Nachtflieger expects to build a custom LSI processor for their future products. The 
processor, called the KDF-10, will be used primarily as an analog sensing and control 
element in a larger electronic environment. As a result, the KDF-10 word size must 
accommodate digital values corresponding to analog signals of up to 12 bits. To 
allow computations on these 12-bit values, Nachtflieger engineers are going to allow 
a full 16-bit word in the KDF-10, along with a number of primitive operations on 
these values. Externally, the KDF-10 will provide four analog-to-digital input ports 
(A-D) that can be read by KDF-10 programs, along with four digital-to-analog out- 
put ports (D-A) that can be written by the program. The KDF-10 will automatically 
perform the A-D and D-A conversion at these ports. 

Being forward thinkers, the engineers at Nachtflieger have designed the KDF-10 as 
a stack machine, similar in concept to the Hewlett-Packard HP-65 handheld pro- 
grammable calculator, where data can be loaded to the top of a stack of data ele- 
ments, automatically pushing existing elements deeper onto the stack. Similar to the 
Reverse Polish Notation (RPN) of an HP-65, arithmetic on the KDF-10 will be 
performed on the topmost stacked elements, automatically absorbing the stacked 
operands as the arithmetic is performed. The designers settled on the following three- 
character operation codes for the KDF-10: 



SIZ n reserves n 16-bit elements as the maximum size of the KDF-10 

operand stack. This operation code must be provided at the begin- 
ning of the program. 

RDM i reads the analog signal from input port i (0, 1, 2, or 3) to the top 

of the stack. 

WRM o writes the digital value from the top of the stack to the D-A output 

port given by o (0, 1, 2, or 3). The value at the stack top is 
removed. 

DUP duplicates the top of the KDF-10 stack. 

SUM adds the top two elements of the KDF-10 stack. Both operands 

are removed, and the resulting sum is placed on the top of the 
stack. 
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LSR n performs a logical shift of the topmost stacked element to the right 

by n bits (1, 2,. . .,15), replacing the original operand by the shifted 
result. LSR n performs a division of the topmost stacked value by 
the divisor 2 to the n power. 

JMP a branches directly to the program address given by label a. 

Because the KDF-10 does not exist, except in the minds of the Nachtflieger engineers, 
the software designers decided to use the macro facilities of MAC to emulate the 
KDF-10, using the 8080 microcomputer. 

Listing 9-6 shows an example of a program for the KDF-10 that was processed by 
MAC using the macro library defined by the Nachtflieger software group. In this 
situation, the KDF-10 is connected to four temperature sensors attached at strategic 
places on the machining equipment. The program continuously reads the four input 
values from the A-D ports and computes their average value by summing and divid- 
ing by four. This average value is sent to D-A output port where it is used to set 
environmental controls. 



AVERAGE THE VALUES WHICH ARE READ FROM ANALOG 
INPUT PORTS* WRITE THE RESULTING VALUE TO ALL 
THE D-A OUTPUT PORTS. 







MACLIB STACK 


5READ THE STACK MACHINE OPCODE 


0000 




SIZ 


20 


.CREATE 20 LEVEL WORKING STACK 


012E 


LOOP: 


RDM 





iREAD A-D PORT 


0134 




RDM 


1 


5READ A-D PORT 1 


0136 




RDM 


2 


5READ A-D PORT 2 


013A 




RDM 


3 


'.READ A-D PORT 3 




5 


ALL 


FOUR VALUES 


ARE STACKED » ADD THEM UP 


013E 




SUM 




5AD3+AD2 


0140 




SUM 




i(AD3+AD2)+ADl 


0142 




SUM 




5((AD3+AD2)+AD1)+AD0 




i 


SUM 


IS AT TOP OF 


THE STACK. DIVIDE BY 4 


0144 




LSR 


2 


5SHIFT RIGHT TWO = DIV BY 4 


0152 




WRM 





5WRITE RESULT TO D-A PORT 


0156 C32E01 




JMP 


LOOP 


!G0 GET ANOTHER SET OF VALUES 



Listing 9-6. A-D Averaging Program Using Stack Machine 
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As shown in Listing 9-6, the program begins by reserving a stack of 20 elements, 
a much larger stack than required for this application, since a maximum of four 
elements are actually stacked. The program then cycles following LOOP, where the 
values are read and processed. The four operations RDM 0, RDM 1, RDM 2, and 
RDM 3 read all four temperature sensors, placing their data values in the stack. The 
three SUM operations that follow the read operations perform pairwise addition of 
the temperature values, producing a single sum at the top of the stack. Because the 
average value is wanted, the LSR 2 operator is applied to the stack top to perform 
the division by four. Finally, the resulting average is sent to the D-A port using the 
WRM operation code. Control then transfers back to LOOP, where the entire 
operation is performed again. 

Because Nachtflieger designers are emulating KDF-lOs using 8080s, they have cre- 
ated the macro library file, called STACK.LIB, as shown in Listing 9-7. A macro is 
shown in this listing for each of the KDF-10 opcodes, starting with the SIZ operator. 
In this case, the program origin is set, since this must be the first opcode in the 
program, and the stack area is reserved. Note that double words of storage are 
reserved because a 16-bit word size is assumed. The DUP, SUM, and LSR operators 
follow the SIZ macro. In each case, the KDF-10 stack top is assumed to be in 8080's 
HL register pair. Further, each operation that pushes the KDF-10 stack causes the 
element in the 8080 HL pair to be pushed to the 8080 memory area reserved by the 
SIZ opcode. 



siz mac ro size 

55 set "orS" and create stack 

local stack 551abel on the stack 

or* lOOh i 5 at base of TPA 

1 k i sp tstack 

Jmp stack 55past stack 

ds size*2 55double precision 
stack: endm 
5 

dup macro 
55 duplicate top of stack 

push h 

endm 



Listing 9-7. Stack Machine Opcode Macros 
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sum macro 

;; add the top two stacK elements 
pop d 5 5 top- 1 to de 
dad d 5 ibacK to hi 
endm 

! 

lsr macro len 

5! logical shift ritfht by len 

; 5 sene rate inline 
5 5clear carry 

i 5 rotate with hi 3h 



5 5bacK with hi Sh bit 





rept 


len 




x ra 


a 




iitoy 


a >h 




rar 






mov 


h »a 




mov 


ail 




rar 






MOV 


1 »a 




endm 






endm 




adcO 


equ 


1080h 


adcl 


equ 


1082h 


adc2 


equ 


1084h 


adc3 


equ 


108Gh 


dacO 


equ 


1090h 


dacl 


equ 


1092h 


dac2 


equ 


1094h 


dac3 


equ 


1096h 



ia-d converter 

ia-d converter 1 

5a-d converter 2 

ia-d converter 3 

5d-a conve rte r 

id-a conve rte r 1 

id-a converter 2 

5d-a conve rte r 3 



rdm macro ?c 

55 read a-d converter number "?c" 

push h iiclear the stack 
5 read from memory mapped input address 

Ihld adc&?c 

endm 
5 

wrm macro ?c 
55 write d-a converter number "?c" 

shld dac&?c 55value written 

pop h 5 5 resto re stacK 

endm 



Listing 9-7. (continued) 



112 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 9.2 Machine Emulation 

The DUP opcode simply pushes the HL register pair to memory since the HL pair 
is not altered in the 8080 during this operation. In the case of the SUM operator, it 
is assumed that the KDF-10 programmer has somehow loaded two values to the 
KDF-10 stack. So the HL registers contain the most recently loaded value, and the 
8080 memory stack contains the next-to-most recently stacked value. The POP D 
operation loads the second operand to the DE pair in the 8080 CPU. Then the 
topmost value and next to top value are added, using the DAD D operation. The 
resulting operand goes into the HL register pair. This is necessary in the KDF-10 
emulation because the top of the KDF-10 stack is located in the 8080's HL register 
pair. 

The LSR opcode is more complicated. The values must go through the accumula- 
tor because the 8080 does not support a double precision (16-bit) right shift of the 
HL register pair. Thus, the LSR macro contains a REPT loop that generates inline 
machine code for each right shift. The inline machine code performs the right shift 
by first clearing the carry (XRA A), followed by a high-order right shift by one bit 
(MOV A,H followed by RAR), then by a low-order bit shift (MOV A,L followed by 
RAR). Note that an intermediate bit can move from the high-order byte to the low- 
order byte using the carry between high- and low-order byte shifts. 

In Listing 9-7, the RDM and WRM operation codes are defined by memory- 
mapped input/output operations. That is, memory locations 1080H through 1087H 
are intercepted external to the 8080 microprocessor and treated as external read 
operations. Thus, a load from locations 1080H and 108 1H to HL is treated as a 
read from A-D device 0, rather than from RAM. This operation is simple to perform 
in the KDF-10 emulation because all program addresses are assumed to be below 
1000H, so any 8080 address bus values beyond 1000H must be memory mapped I/O. 

As a result, ADC0 through ADC3 correspond to the locations where A-D values 
through 3 are obtained. Similarly, the D-A output values that are written to locations 
1090H through 1097H are intercepted as memory mapped output values that are 
sent to the D-A converters rather than to RAM. 

The RDM instruction is emulated by simply performing an LHLD from the appro- 
priate memory mapped input address, constructed through concatenation of the dummy 
parameter. The HL value is first pushed because the KDF-10 RDM opcode performs 
this task automatically. Then the new value is loaded into the HL register pair. 
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The WRM opcode definition is similar, except the value to write is assumed to 
reside at the top of the KDF-10 stack and thus appears in the 8080 HL register pair. 
The value is written to the memory mapped output location, and the value is removed 
from the HL pair by restoring HL from the 8080 stack. 

To see the actual code generated by each of these macros, Listing 9-8 shows the 
same averaging program as given in Listing 9-6, except that the generated 8080 
instructions are interspersed throughout the listing file. Listing 9-8 is the usual output 
from MAC; Listing 9-6 was generated using the parameter -M, which suppresses 
generated mnemonics. Compare Listings 9-6, 9-7, and 9-8, so that you understand 
the macro expansion processes. 



AVERAGE THE VALUES WHICH ARE READ FROM ANALOG 
INPUT PORTS. WRITE THE RESULTING VALUE TO ALL 
THE D-A OUTPUT PORTS, 







MACLIB 


STACK 


.READ THE 


STAC 






SIZ 


20 


5CREATE 2C 


LEV 


0100+ 




ORG 


100H 






0100+312E01 




LXI 


SP»??0001 




0103+C32E01 




JMP 


??0001 






0106+ 




DS 


20*2 








LOOP: 


RDM 





5READ A-D 


PORT 


012E+E5 




PUSH 


H 






012F+2A8010 




LHLD 


ADC0 










RDM 


1 


5READ A-D 


PORT 


0132+E5 




PUSH 


H 






0133+2A8210 




LHLD 


ADC1 










RDM 


2 


5READ A-D 


PORT 


0136+E5 




PUSH 


H 






0137+2A8410 




LHLD 


ADC2 










RDM 


3 


5READ A-D 


PORT 


013A+E5 




PUSH 


H 






013B+2A8B10 




LHLD 


ADC3 







Listing 9-8. Averaging Program with Expanded Macros 



114 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.2 Machine Emulation 



013E+D1 
013F+19 



0140+D1 
0141+19 



0142+D1 
0143+19 



0144+AF 
0145+7C 
014G+1F 
0147+67 
0148+7D 
0149+1F 
014A+GF 
014B+AF 
014C+7C 
014D+1F 
014E+G7 
014F+7D 
0150+1F 
0151+6F 

0152+229010 
0155+E1 
0156 C32E01 



ALL FOUR VALUES ARE STACKED* ADD THEM UP 
IAD3+AD2 



i(AD3+AD2)+ADl 



5((AD3+AD2)+AD1)+AD0 



SUM 




POP 


D 


DAD 


D 


SUM 




POP 


D 


DAD 


D 


SUM 




POP 


D 


DAD 


D 


SUM 


IS AT TOP 01 


LSR 


2 


XRA 


A 


MOV 


AtH 


RAR 




MOV 


HtA 


MOV 


A.L 


RAR 




MOV 


L.A 


XRA 


A 


MOV 


A»H 


RAR 




MOV 


H»A 


MOV 


A»L 


RAR 




MOV 


L»A 


WRM 





SHLD 


DACO 


POP 


H 


JMP 


LOOP 




Listing 9-8. 



iSHIFT RIGHT TWO = DIV BY 4 



iWRITE RESULT TO D-A PORT 



5G0 GET ANOTHER SET OF VALUES 



(continued) 



A problem arose at Nachtflieger MW, however, that had to be rectified. Although 
programs could be effectively written for the KDF-10 computer using the 8080 emu- 
lation, they could not be effectively debugged. The program in Listing 9-8, for exam- 
ple, could be tested under the CP/M Dynamic Debugging Tool (see CP/M documen- 
tation), but the program required monitoring and tracing at the 8080 machine code 
level. It became clear that higher level debugging tools were necessary. 
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As a result, Nachtflieger designers added several pseudo opcodes that allow debug- 
ging traces. The opcodes can be interspersed in the program and selectively enabled 
and disabled, depending on the debugging needs. In production, all debugging traces 
are disabled, resulting only in absolute port I/O. The additional debugging opcodes 
are listed below. 

PRN msg Print the message given by "msg" at the debugging console when- 

ever the print trace is enabled. The message must be enclosed in 
angle brackets. 

DMP Print the value of the top element in the KDF-10 stack in 

hexadecimal. 

TRT t Set machine code trace option to true. Each time a KDF-10 machine 

operation is executed, the opcode is printed, followed by the 
approximate KDF-10 machine code address, followed by the top 
two elements of the KDF-10 stack, in the format: 

OPC oploc top top' 

where OPC is the opcode, oploc is the location, top is the top 
element, and top' is the second to the top element, all in hexadec- 
imal notation. 

TRF t Disable the machine code trace. Only the KDF-10 instructions 

that physically appear between the TRT and TRF opcodes are 
shown in the trace. 

TRT p Enable the print/read trace. PRN opcodes that follow produce 

output at the debugging console, and are otherwise treated as 
comments. Further, RDM and WRM opcodes prompt and dis- 
play data at the debugging console. 

TRF p Disable the print/read trace. Only the PRN, RDM, and WRM 

instructions that physically appear between TRT and TRF inter- 
act with the console. 
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The traces are disabled at the beginning of the program and must be explicitly 
enabled with TRT opcodes. 



AVERAGING PROGRAM WITH INTERSPERSED DEBUG CODE 



0000 
0103 
0103 
0103 
012E 
01F0 
022C 
0267 
02BA 
02A5 
02A8 
02E3 
02EB 



MACLIB DSTACK iREAD THE STACK MACHINE OPCODES 

SIZ 20 iCREATE 20 LEVEL WORKING STACK 

TRT T iMACHINE CODE TRACE ON 

TRT P iPRINT TRACE ON 

PRN (TRACE FOR AVERAGING PR0GRAM> 

LOOP: RDM iREAD A-D PORT 

DMP iWRITE TOP OF STACK 

RDM 1 iREAD A-D PORT 1 

DMP iWRITE TOP OF STACK 

RDM 2 iREAD A-D PORT 2 

DMP 5WRITE TOP OF STACK 

RDM 3 iREAD A-D PORT 3 

DMP iWRITE TOP OF STACK 

PRN <FOUR VALUES HAVE BEEN READ> 



0310 
032-3 
0327 
033B 
033E 
0352 
0378 



ALL FOUR VALUES ARE STACKED* ADD THEM UP 

SUM 5AD3+AD2 

DMP iWRITE FIRST SUM 

SUM i(AD3+AD2)+ADl 

DMP iWRITE SECOND SUM 

SUM i((AD3+AD2)+ADl)+AD0 

PRN <VALUES HAVE BEEN ADDED> 

DMP iWRITE SUM OF VALUES 



037B 
0389 
03B1 
03B4 
03EE 
03F1 



SUM IS AT TOP OF THE STACK. DIVIDE BY H 

LSR 2 5SHIFT RIGHT TWO = DIV BY 4 

PRN < AVERAGE VALUE CALCULATED)- 

DMP iWRITE AVERAGE VALUE 

WRM iWRITE RESULT TO D-A PORT 

BRN LOOP iGO GET ANOTHER SET OF VALUES 

XIT 5EMIT EXIT CODE 



Listing 9-9. Averaging Program with Debugging Statements 
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Listing 9-9 shows the averaging program of Listing 9-6 with interspersed debug- 
ging statements. The opcodes TRT t and TRT p are executed at the beginning of the 
program, enabling all trace options throughout the execution. The PRN statement 
above the LOOP label prints the initial sign-on; the DMP statements after each read 
operation give the value of the A-D port. Upon completion of the four-element read, 
the PRN opcode indicates this fact. Each SUM operator is followed by a DMP 
opcode that shows the current sum. Finally, the PRN and DMP opcodes display the 
final average value that is being sent to D-A port 0. The XIT opcode shown at the 
end of the program is discussed below. 

Listing 9-10 shows the execution of the averaging program under DDT. Note that 
the program headings appear at the points in the program where PRN opcodes are 
placed. Further, the console is prompted for input in the case of an RDM opcode, 
giving the absolute memory mapped input address in decimal, while the WRM 
instruction produces a "D-A OUTPUT . ." message that shows the absolute memory 
mapped output address and the data that is written. 

The opcodes are also traced showing the opcode mnemonic, address, and top two 
stacked elements. The RDM trace at the beginning, for example, shows the instruc- 
tion address 01AD, which is in the range of the first RDM of Listing 9-9 (012E to 
01EF), and is followed by the two values 0111 (the value just read) and C21D 
(garbage value, because only one element is stacked). The trace is easily followed at 
the KDF-10 level, showing each value that is read in and the operations performed 
upon these values. Upon completion of the debugging process under CP/M, the TRT 
opcodes are removed and the program is reassembled, leaving only the 8080 instruc- 
tions required in the production machine. Nachtflieger systems engineers then take 
the resulting program and test its operation in a hardware environment. 
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F\>ddt aver, hex 
DDT VERS 1.4 
NEXT PC 
040G 0000 
-3100 

TRACE FOR AVERAGING PROGRAM 

A-D INPUT AT 4224 111 

RDM 01AD 0111 C21D 

(TOP)= 0111 

A-D INPUT AT 422B 222 

RDM 0255 0222 0111 

(TOP)= 0222 

A-D INPUT AT 4228 555 

RDM 0293 0555 0222 

(TOP)= 0555 

A-D INPUT AT 4230 444 

RDM 02D1 0444 0555 

(TOP)= 0444 

FOUR VALUES HAVE BEEN READ 

SUM 0312 0999 0222 

(TOP)= 0999 

SUM 0329 OBBB 0111 

(TOP)= OBBB 

SUM 0340 OCCC C21D 

VALUES HAVE BEEN ADDED 

(TOP)= OCCC 

AVERAGE VALUE CALCULATED 

(TOP)= 0333 

D-A OUTPUT AT 4240 0333 

WRM 03DC 793B C21D 

A-D INPUT AT 4224 



Listing 9-10. Sample Execution of AVER Using DDT 



Nachtflieger engineers quickly realized that the KDF-10 design had a number of 
deficiencies due to the paucity of arithmetic operators and the total absence of con- 
ditional branching instructions. Further, there was no provision for variable storage 
other than the stack. Thus, the KDF-11 naturally evolved from the KDF-10, incor- 
porating these features. Table 9-1 lists the operation codes of the KDF-11. 
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Table 9-1. KDF-11 Operation Codes 



Code 



Meaning 



DCL v,n 



LITc 



VAL v,i,c 



STO v,i,c 



DIF 



GEQa 



BRNa 



Declare (reserve) storage for a variable by the name v, with 
optional size n. If n is omitted, then n - 1 is assumed. All DCL 
opcodes must follow the XIT opcode given below. 

Load the value of the literal constant c to the top of the KDF- 
11 stack. 

Load the value of the variable v optionally indexed by the vari- 
able i with the optional constant offset c. VAL V loads the value 
of V to the top of the stack. VAL V,I loads the value located at 
the address of V plus the index value contained in I. VAL V,I,3 
loads the value at location V plus the index I, plus the constant 
index 3. In all cases, the value is placed at the top of the KDF- 
11 stack. 

Store the value obtained from the KDF-11 stack to the address 
given by v, plus the optional index i, plus the optional constant 
index given by c. The top element of the KDF-11 stack is removed. 

Subtract the top element of the KDF-11 stack from the next- to- 
top element of the stack and replace both operands by their 
difference. 

Test the next-to-top element (top') against the top of stack ele- 
ment (top), and branch to the label given by "a" if top' is greater 
than or equal to top. If not, program control continues to the 
next opcode in sequence. 

Replace the JMP instruction in the KDF-10 architecture to allow 
complete separation of the KDF-11 and 8080 machines. 



Listing 9-11 gives the macro library that was constructed by the Nachtflieger soft- 
ware group for KDF-11 machine emulation. More than half of the macro library 
implements trace and debugging functions. The remaining components implement 
the KDF-11 opcodes themselves. Each major section of this macro library, called 
DSTACK.LIB, is briefly described below, followed by an example of its use. 
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macro library for a zero address machine 

* besin trace/dump utilities * 

5 s /stem entry 
iread a character 
iwrite character 
iwrite buffer 
itransient program area 
idata area 
icarriaSe return 
i 1 ine feed 

i it race debus set false 
5 jprint debus" set false 



bdos 


eiu 


0005h 


rchar 


equ 


1 


wchar 


equ 


2 


wbuf f 


emi 


9 


t ran 


eiu 


lOOh 


data 


equ 


HOOh 


c r 


e=iu 


Odh 


If 


equ 


Oah 


debuSt 


set 





debusp 


set 






M5SC 



macro pr 

print message 'pr' at console 

if debuSp iiprint debus on' 



local 


pmsS tmsS 


Jmp 


pmsS 


db 


or »lf 


db 


'8tPR*' 


push 


h 


Ixi 


d unss 


my i 


c twbuff 


call 


bdos 


POP 


h 


endif 




endm 





iilocal message 
i iaround message 
5 5 return carriage 
iiliteral message 
isave top element of stacK 
ilocal message address 
iwrite buf f e r 'til $ 
5print it 

irestore top of stack 
iend test debudp 



uSen macro 

55 generate utilities for trace or dump 

local psub 

Jmp psub iiJump past subroutines 

@ch: J? write character in reS-a 

mov e >a 

my i c »wchar 

Jmp bdos iireturn thru bdos 
5 5 

@nb: iiwrite nibble in res-a 

adi 90h 

daa 

aci 40h 

daa 

Jmp @ch iireturn thru @ch 
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@hxi 



@ad 



@in: 



@inO: 



iinl 



nur 

push 

rrc 

rrc 

rrc 

rrc 

an i 

call 

POP 

an i 
Jmp 



ite hex value in resf-a 

psw 5 5save low byte 



Ofh 
@nb 

PSW 

Ofh 
8nb 



5 imask hi ah nibble 
5 Jprint hish nibble 



5 Jprint low nibble 



55write address value in hi 



push 
Mv i 
call 

POP 
WO V 

push 
call 

POP 

mov 
Jmp 

i * read 

mv i 

call 

lxi 

push 

mv i 

call 

POP 

sui 

cpi 

Jc 

may be 

sui 

cpi 

rnc 

5 5 in 

rept 

dad 

endw 

ora 

mov 

Jmp 



ra 



h 

a > ' 

@ch 

h 

a >b 

h 

@hx 

h 

a»l 

@hx 

hex 
a > ' 
@ch 
h»0 
h 

c > r 
bdo 
h 

'0' 
10 
@in 

hexa 
'A' 
IB 

nSe f 

a 

h 



5 5save value 
! 51eadinS blank 
!5ahead of address 
5 5hi «fh byte to a 

5 5oopy back to stack 
5 5 w r i te hi Sh byte 

5 5 low byte 

5 iwrite low byte 

value to hi from console 
Heading space 
ito console 
JstartinS value 
5save it for char read 

char ijread character function 
Jread to accumulator 
! value beinS built in hi 
JnorMalize to binary 
Jdecimal? 

1 5icarry if »1 > ♦ ♦ ♦ >9 

decimal a t . ♦ . »f 

-'0'-10 

5 !a through f? 
iiretum with assuMed cr 
multiply by 4 and add 

55shift a 



1 5 « add didit 

1 >a 5 5and replace value 

@inO jJfor another disit 



Listing 9-11. (continued) 

122 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.2 Machine Emulation 



psub : 
uSen 



t race 



mac ro 

redef to include once 

endm 

uSen ((Generate first time 

endm 

* end of trace/dump utilities * 

* besin trace (only) utilities * 

mac ro code »mname 

trace macro Siven by mname i 

at location Siuen by code 

local psub 

uSen iisfenerate utilities 

Jwp psub 



itl: 


ds 


2 ; 


(temp for rea-1 


@t2: 


ds 


2 ; 


itemp for rea-2 


@tr: 


5 5 1 race 


macro call 


5 5 


bc = code 


add ress » 


de=messa3e 




shld 


itl 5 


(Store top res 




POP 


h 5 


i return add ress 




xthl 




5 res-2 to top 




shld 


it2 ; 


(Store to temp 




push 


psw ; 


5 save flaSs 




push 


b ; 


isaye ret address 




mu i 


ctwbuff ; 


(Print buffer func 




call 


bdos 5 


(Print macro name 




POP 


h ; 


!code address 




call 


iad ! 


{printed 




lhld 


eti ; 


5top of stack 




call 


iad ; 


jprinted 




lhld 


@t2 ; 


itOP-1 




call 


iad ! 


iprinted 




POP 


psw ; 


5f lasfs resto red 




POP 


d ; 


5return address 




lhld 


@t2 ; 


(tOP-1 




push 


h ; 


5 resto red 




push 


d ; 


5 return add ress 




lhld 


@tl ! 


(top of stack 




ret 
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psub: 55past subroutines 

5 5 

trace macro c >m 

5 5 redefined trace* uses @tr 

local pinsStitisS 

JfilP PlrtSS 

msS: db c r >lf 5 5c r >lf 

db x 8cM$ ' 5 5mac name 

pmss: 

lxi b *c 5 5code add ress 

lxi d »ms$ 5 5mac ro name 

call @tr 5!tot race it 

endm 
55 back to original macro level 

t race code »mname 

endm 
5 

trt macro f 
5 5 turn on f las "f" 
debui&f set 1 i iprint/t race on 

endm 
i 

trf macro f 
5 5 turn off flaS "f" 
debuJ&f set 5 5t race/print off 

endm 
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?tr 



dmp 



@dm: 



@dmO: 



mac r 

chec 

if 

t rac 

endm 

##** 

* 

# 

mac r 
dump 
n el 
1 oca 
usen 
Jmp 
5 5 du 
de = m 
hl = b 
push 
push 
my i 
call 

POP 
POP 

mov 

o ra 

rz 

dc r 

mov 

inx 

mov 

inx 

push 

push 

xchS 

call 

Jmp 



o m 

k debuit totfSle before trace 

debust 
e lit hi 



***## 
e 
b 

***** 

v 
uari 

ement 

1 p 



MP Ut 

S3 ad 
ase a 
h 
b 
c 
b 
b 
h 



*******#*******##******##******# 

nd trace (only) utilities * 

etfin dump (only) utilities * 

*******#****####*****#**#*****#* 

name »n 

able vname for 

s (double bytes) 

sub jipast subroutines 

! iSen inline routines 
sub !5past local subroutines 
i 1 ity pros ram 
dresst c=element count 
ddress to print 

5 ibase address 

! 5e lement count 
*wbuff !5write buffer func 
dos 5 JmessaSe written 

5 5 recal 1 count 

i 5 recal 1 base add ress 

! iend of list? 



a >c 



h 

d >m 
h 
h 
b 

@ad 
SdmO 



jreturn if so 
5decrement count 
inext item (low) 

inext item ( hi 3h ) 

jready for next round 

5save print address 

5s aye count 

5 data ready 

! print item value 

5for another value 



Bdt: 



jjdump top of stacK only 



prn 


< ( t O P ) = > 


5 i"(T0P) = " 


push 


h 




call 


@ad 


i 5value of hi 


POP 


h 


! !top resto red 


ret 
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psub 
5 ! 
dfitp 



mac ro ?v >?n 

redefine dump to use @dm utility 

local PwsSxrtsS 

special case if null parameters 

if nul vname 

dump the top of the stacK only 

call idt 

exitm 

endif 

otherwise dump uariable name 



icrlf 

imessase 

ihl=address 

idea r active f laS 

imessase to print 

iuse lensfth 1 





Jmp 


pmsS 


ms3: 


db 


cr >lf 




db 


'&?U=$' 


pmsS : 


ad r 


?V 


active 


set 







lxi 


d >msd 




if 


nul ?n 




mvi 


c »1 




else 






mui 


c >?n 




endif 






call 


Idm 




endm 






dfflp 


vname »n 




endm 





5 ito pe rf o rm the dump 
i iend of redefinition 



#*##*###***##*#######**####***###*##♦**#* 

* end dump (only) utilities* * 

* bes(in stack machine opcodes * 

stive set iactiue register flaS 



@stK 



mac ro 
o r$ 



size 
t ran 



»!set to transient area 



create a stacK when "xit" encountered 



set 
lxi 
endm 



size 55save for data area 
sp >stacK 
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save macro 

!! checK to ensure "enter" properly set up 

if stack !5is it present? 

endif 
save macro 5!redefine after initial reference 

if active Jielement in hi 

push h 5 5save i t 

endif 
active set 1 55set active 

endm 

save 

en dm 

rest macro 

55 restore the top element 

if not active 

pop h iirecalltohl 

endif 
active set 1 iimarK as active 

endm 
5 

clear macro 
55 clear the top active element 

rest 55ensure active 

active set !5cleared 

endm 
5 

del mac ro vname »si ze 
55 label the declaration 
vname : 

if nul size 

ds 2 5 !one wo rd req ' d 

else 

ds size*2 55double words 

endm 
5 

lit mac ro val 
55 load literal value to top of stacK 

save 5 5save if active 

lxi htval 551oad literal 

?tr lit 

endm 
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adr macro base »inx >con 

55 load address of base» indexed by inx» 

55 with constant offset Siven by con 



5 5 p u s h if active 
nul inx&con 
h >base 55address of base 

i isiwple address 



saue 

if 

lxi 

e x i t in 

endif 

must be inx and/or con 



if 
lxi 
else 
1 hid 

dad 

if 

lxi 

dad 

endif 

endif 

lxi 

dad 

en dm 



nul inx 

h »con*2 5 iconstant 

inx ! I in d e x to hi 

h ;?double precision 
not nul con 



d »con*2 
d 



d tbase 
d 



5 d o u b 1 e const 
iadded to inx 
5not nul con 
inul inx 
iready to add 
ibase+inx*2+con*i 



val 



mac r 

Set 

chec 

if 

save 

1 hid 

else 

"adr 

adr 

mo v 

inx 

mo v 

xchs 

endi 

?tr 

en dm 



o b »i »c 

value of b+i+c to hi 

K simple case of b only 

nul i&c 

jjpush if active 

b 5 5 1 o a d directly 

" pushes active registers 
b ti »c 5 iadd ress in hi 
iilow order byte 



e tm 
h 
d tm 



val 



5 i h i 3 h order byte 
5ibacK to hi 



i 5t race set? 



Listing 9-11. (continued) 



128 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.2 Machine Emulation 



sto Mac ro b »i >c 

5! store the value of the top of stack 

5i 1 e a v i n S the top element active 
if nul i&c 

rest Jiactivate stack 

shld b iistored directly to b 



else 
ad r 

POP 

mov 
inx 

MOV 

endi 

clea 

?tr 

endm 

mac r 

rest 

add 

POP 

dad 
?tr 
endm 



b t i » c 

d 5 5 value is in de 

m >e 5 5 low byte 

h 

m>d 5 ih i 3h byte 
f 
r ! imark empty 

sto 5 ! t race? 



55restore if saved 
the top two stack elements 
d iitop-ltode 
d 5 iback to hi 
sum 



dif 



mac ro 

compute difference between top elements 



rest 




Srestore if saved 


POP 


d 


5top-l to de 


mo v 


a i e 


5 top-1 low byte to a 


sub 


1 


5 low o rde r difference 


mov 


1 »a 


iback to 1 


mov 


a.d 


! top-i hi Sh byte 


sbb 


h 


5hi 0h order dif f e rence 


mov 


h >a 


5back to h 



carry flaS may be set upon return 

?tr dif 

endm 
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lsr macro 1 en 

55 logical shift risht by len 

i iact iuate stacK 
5 JSenerate inline 
5 5clear carry 

5 5 rotate with hi sfh 



55back with hi 3h bit 



rest 




rept 


len 


x ra 


a 


MOV 


a »h 


rar 




mov 


h »a 


IUDU 


a»l 


rar 




mov 


1 -a 


endm 




endm 




mac ro 


lab 


JUMP 


to lab 


equal 


to ( t 


dif 




clear 




?tp 


Seq 


Jnc 


lab 


J2 


lab 



3eq 



5 5coi«pute dif f e rence 
!5clear active 

55no carry if Greater 
5 !ze ro if equal 

drop through if neither 

endm 

dup macro 

duplicate the top element in the stacK 

rest 5 5ensure active 

push h 

?tr dup 

endm 
5 

brn macro addr 
5 5 b ranch to add ress 

Jwp addr 

endm 
5 
xit macro 

?t r xit 5 5t race on? 

Jmp lirestart at OOOO 

or3 data 55start data area 

ds @stk*2 55obtained from "siz" 



stack: endm 
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adcO 


e<=iu 


adc 1 


eiu 


adc2 


emi 


adc3 


equ 


dacO 


equ 


dacl 


BRU 


dac2 


eiu 


dac3 


eiu 


rwt race 
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* memory mapped i/o section * 

input values which are read as if in memory 
1080h ia-d converter 
1082h 5a-d converter 1 
1084h ia-d converter 2 
1086h 5a-d converter 3 

1090h id-a converter 

1082h id-a converter 1 

1094h id-a converter 2 

1096h id-a converter 3 

mac ro msS »ad r 
5! read or write trace with message 
5 5 3 i v e n by " m s 4 " t o / f r o m " a d r " 

prn <ms3 at adr> 

endm 
5 

rdm macro ?c 
5! read a-d converter number "?c" 

save 5!clearthestack 

if debuSp iistop execution in ddt 

rwtrace <a-d input >»% adc&?c 

u tf e n 5 i ensure @in is present 

call @in 5 ivalue to hi 

shld adc&?c iisimulate memory input 

else 
I! read from memory mapped input address 

lhld adc&?c 

endif 

?t r rdm i it racing? 

endm 
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macro ?c 

write d-a converter number 



rest 


! ! restore stack 


if 


deb u tf p 5 5 1 r a c e the output 


rwt race 


<d-a output >»X dac&?c 


utfen 


55include subroutines 


call 


@ a d 5 5 w r i t e the value 


endif 




shld 


dac&?c 


?tr 


w rm 5 !t racing output? 


clear 


5 5 r e m o v e the value 


endm 




**##*****##****#**##*#**#****#*##******** 


* 


end of macro library * 


*******#####*#***#******####**# *#*******# 




Listing 9-11. (continued) 



The first portion of the library, which is principally concerned with debugging 
functions, begins with CP/M system calls, function numbers, and equates for non- 
graphic characters, similar to the examples given earlier. Although these values are 
not necessary for operation of the KDF-11, they are necessary for the debugging 
functions that operate when the TRT opcode is in effect. Following the CP/M equates, 
the toggles DEBUGT and DEBUGP are set to false (0 value), reflecting the conditions 
of the debugging switches given by TRT and TRF. When DEBUGT is true (1 value), 
machine operation codes are traced. Similarly, when DEBUGP is true, PRN, RDM, 
and WRM operations interact with the console. 

The PRN macro, for example, produces an inline message with a call to CP/M to 
write the message whenever the DEBUGP toggle is true. Otherwise, the PRN pro- 
duces no generated code. 

The UGEN macro that follows PRN is called the first time the debugging subrou- 
tines are required by trace or print/read opcodes. When invoked, the UGEN macro 
produces several inline subroutines that are used throughout the debugging process. 
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If no trace or print/read functions are invoked during the assembly, UGEN is not 
invoked. Thus no inline subroutines are included for debugging. If UGEN is invoked, 
the subroutines shown below are included inline: 

@CH writes a single ASCII character to the console. 

@NB writes a single half byte (nibble) to the console. 

@HX writes a full hexadecimal byte value at the console. 

@AD writes a full address (double byte) value with preceding blank. 

@IN reads a hexadecimal value from the console to HL. 

Upon including these subroutines, UGEN then redefines itself to an empty macro 
body so that the subroutines are not included on subsequent invocations of UGEN. 
This ensures that the inline subroutines are included only once, and only if they are 
required by the debugging macros. 

The SIZ macro is similar to the opcode defined for the KDF-10, except that the 
size of the stack is saved for later declaration in the data area (see the XIT opcode). 
Throughout the opcode macros, the SAVE and REST macros save and restore the 
HL register pair, based on the ACTIVE flag. The CLEAR macro, however, marks the 
top element of the KDF-11 stack as deleted. 

The DCL macro simply sets up the variable name VNAME as a label and follows 
the label by a DS that reserves the specified number of double words. The DCL 
opcodes must all occur at the end of the KDF-11 program, following the XIT opcode. 

The LIT opcode is emulated with a macro that first SAVEs the stack top, possibly 
generating an HL push. The literal value is then loaded directly into the HL register 
pair. The ACTIVE flag is set on completion of this macro because SAVE always 
marks HL as active. 
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The ADR macro is a utility macro used in the VAL, STO, and DMP opcodes to 
build the address of a particular variable, with optional variable and constant offsets, 
in the HL register pair. Based on the optional parameters, ADR either loads the base 
address directly to the HL pair or constructs the address using HL and DE for 
indexing. Thus, the following invocations of ADR (in the left column) produce the 
machine code in the right column. 

ADR X LXI H»X 

ADR X»I LHLD I 

DAD H 



LXI D 

DAD D 

ADR X»I»3 LHLD I 

DAD H 

LXI D 

DAD D 

LXI D 

DAD D 



ADR 



t A 



LXI 


H »6 


LXI 


D tX 


DAD 


D 



The final address for the optionally indexed variable remains in the HL register pair. 
The code within the ADR macro can be improved slightly by providing a constant 
offset. That is, the following invocations in the left column produce the machine 
code in the right column by redefining the ADR macro. 

ADR X»I»3 LHLD I 

LXI D»X+B 
DAD D 

ADR X»»3 LXI HtX+G 

As an exercise, redefine ADR to generate this improved machine code sequence. 
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The VAL macro loads a variable value to the stack. STO stores the top of stack 
value to memory. ADR constructs the address of the variable whenever optional 
indexing is specified. Otherwise, LHLD or SHLD directly accesses the variable. Again, 
slight improvements in generated code can be obtained by providing a constant offset 
with no variable index. 

The opcodes LIT, VAL, and STO all end with an invocation of the ?TR macro 
which, as discussed above, checks the DEBUGT flag. If true, the ?TR macro invokes 
TRACE with the machine code address and opcode name for display at the debug- 
ging console. The ?TR macro invocation produces no machine code trace when 
DEBUGT is false. 

The SUM opcode first invokes REST to ensure that the HL register pair contains 
the topmost KDF-11 element. The second to top element is then loaded to the DE 
pair and added to HL, producing an active KDF-11 element in HL. ACTIVE is true 
at this point, because REST always leaves the flag set to true. 

The DIF opcode definition is similar to SUM, except that the 8080 accumulator 
computes the 16-bit difference between the top two KDF-11 stacked elements. 

The LSR macro defines the KDF-11 logical shift right operation. The REST macro 
is first invoked to ensure that HL is active, followed by a repetition of the machine 
code required to perform a 16-bit right shift of the HL register pair. In the case of a 
long shift, there is a considerable amount of inline machine code for the operation. 
Thus, it is a useful exercise to redefine LSR, so that it generates an inline subroutine 
to perform the shift operation for values of LEN sufficiently large to warrant the 
subroutine call. Although this requires a subroutine set up and call, the amount of 
generated code can be reduced significantly for programs that make heavy use of the 
LSR operator. 

The GEQ macro follows the LSR definition and allows conditional branching to 
the specified label address. GEQ begins by computing the difference between the top 
two elements of the KDF-11 stack. This has the side-effect of setting the 8080 carry 
bit if the next to top element exceeds the top element in the KDF-11 stack. The ?TR 
macro eventually leads to the @TR subroutine where the status flags (including the 
carry condition) are saved and restored. Otherwise, GEQ could not count on the 
condition of the carry flag. 
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Further, the 8080 A register contains the least significant byte of the difference 
between DE and HL, so the ORA H produces a zero result if the difference is zero. 
To be complete, the KDF-11 should have a complete range of conditional tests, 
allowing tests for equality (EQL), inequality (NEQ), less than (LSS), greater than 
(GTR), and less than or equal (LEQ). 

The DUP opcode first ensures that the HL register pair is active, then duplicates 
this value by pushing the HL pair to the 8080 stack, emulating a KDF-11 stack push 
operation. Note that the HL pair is active at the end of the DUP macro due to the 
invocation of REST. 

The BRN and XIT macros follow GEQ. The BRN macro simply translates to a 
jump instruction in the 8080. The XIT macro first invokes the ?TR macro to check 
for machine code tracing. A JMP is then emitted, corresponding to a system restart 
in both CP/M and the emulated KDF-11 machine architecture. The XIT macro then 
produces an ORG statement that restarts the assembly process in the data area of 
the emulated environment (1000H, or 4096 decimal). The area reserved for the stack 
is then set up, followed by the declaration of the label STACK at the top of this 
reserved area. Note that the SAVE macro includes the statement sequence: 

IF STACK Mis it present? 
ENDIF 

which ensures that both the SIZ and XIT macros have been included in the assembly. 
If the XIT macro is not included, then the label STACK does not appear unless used 
in the KDF-11 program, and the IF STACK test produces an undefined operand (U) 
error. Further, if the XIT operator is used, but the SIZ is not, then the statement DS 
SIZ* 2 within XIT produces an undefined operand message. Although these tests are 
by no means complete, they detect the most common errors. 

Listing 9-11 also contains the definitions of both the RDM and WRM opcodes, 
based on the memory mapped input/output addresses defined by ADC0 through 
ADC3 for the A-D ports, and DAC0 through DAC3 for the D-A ports. The RWTRACE 
(Read- Write Trace) macro is included for tracing the RDM and WRM macros when 
DEBUGP is true. The MSG argument corresponds either to A-D INPUT for the 
RDM opcode or to D-A OUTPUT for the WRM opcode. The ADR argument corre- 
sponds to the absolute decimal address where the memory mapped input/output is 
taking place. Thus, RWTRACE simply constructs a trace message from its two argu- 
ments and passes this message to PRN for display at the debugging console. 
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The RDM macro reads the port given by the argument ?C (0, 1, 2, or 3). The HL 
register pair is pushed, if necessary, by the SAVE macro, leaving the active flag set 
for the RDM. RDM then generates an invocation of the RWTRACE macro to pro- 
duce the trace message. Note that the argument "% ADC&PC" produces the numeric 
value ADCO, ADC1, ADC2, or ADC3, which is included in the trace message. If the 
% is omitted, only the name, not the value, of the input port address is printed. 
Following the output message, UGEN is invoked to ensure that the utility subrou- 
tines have been included inline. The call to @IN allows you to type a hexadecimal 
value for the simulated A-D input value. This value is subsequently stored to memory 
and left in the HL register pair with ACTIVE true. If DEBUGP is not set, then the 
RDM macro simply loads the HL register pair from the appropriate memory mapped 
input location. Finally, RDM invokes ?TR to check for possible opcode tracing. 

The WRM opcode is similar to the RDM opcode, except that the REST macro is 
first invoked to ensure that the HL registers contain the top element of the KDF-11 
stack. This value is displayed at the debugging console if DEBUGP is true and then 
sent to the appropriate memory mapped output location. 

One application of the emulated KDF-11 machine shows the power of this instruc- 
tion set. As a small part of a machine control system, a KDF-11 processor monitors 
the machine tool head motion. Nachtflieger engineers connect A-D port to a KDF- 
11 processor that reads the instantaneous velocity of the tool head at 1 millisecond 
(ms) intervals. 

The velocity is provided at the A-D port in micrometer (um) increments, and the 
processor is synchronized with the input, so that it halts until the 1 ms interval has 
elapsed. Nachtflieger engineers also guarantee that the tool head is in motion for no 
more than 100 ms before stopping. Thus, with no variations in velocity, if the tool 
moved at the constant rate of 256 um/ms over 50 intervals of 1 ms each, total 
distance traveled by the tool is 

256 um/ms * 50 ms = 1280 um = 1.280 mm 

During its travel, however, the instantaneous velocity of the tool head varies 
according to the roughness of the cut, wear on the parts, and start/stop intervals. 
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Nachtflieger uses the data collected during a cut to monitor these factors and displays 
machine operator information in both digital and analog forms. A primary function 
of the KDF-11 processor in this case is to collect instantaneous velocities during a 
single cut and hold these values for analysis as the tool returns to its starting posi- 
tion. Listing 9-12 shows a KDF-11 program that includes the data collection phase 
and an analysis phase described below. 

The data collection phase of Listing 9-12 occurs between the labels MOVE? and 
COMP; the analysis phase is found between labels COMP and ENDF. The program 
is bounded by the SIZ operator at the beginning and the XIT operator at the end, 
followed by DCL opcodes that reserve data areas. This program also includes debug- 
ging PRN, DMP, TRT, and TRF opcodes for checking out the program. 

As for the DCL statements at the end of Listing 9-12, the vector V is declared with 
length 100 (double bytes), which holds the collected velocities; I and X are temporary 
values used during the collection and analysis phase. The variable TOTAL is a result 
produced by the analysis, as discussed below. 

The program collects data by performing the following steps. The variable I is first 
initialized to 0, corresponding to the first velocity V(0). The program then examines 
the A-D input port for the first nonzero velocity, waiting for the tool head to begin 
its travel. When the first nonzero velocity is read, the collection process proceeds by 
storing the first value at V(0). The index value I is then moved along as data items 
are read, with values placed into V(l), V(2), continuing until a zero value is read, 
indicating the tool has ended its travel. 

Referring to Listing 9-12, note that the KDF-11 opcodes listed before the label 
MOVE? initialize the index I by loading a literal value to the KDF-11 stack, 
followed by a store into the variable I. To follow these operations, the TRT P and 
TRT T traces are enabled. Note, however, that the TRF T opcode stops the machine 
code trace immediately before the MOVE? label. 
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0000 
0103 
0103 
0103 
013G 
01D3 
01E8 



01E8 
0210 
0213 
021B 
021A 
0227 



022A 
0250 
029C 
029F 
02AC 
02AF 
02B3 
02B5 
02B8 
02BB 
02BF 
02CC 
02F4 
02F7 

02FA 
031A 

032D 
0330 
0331 
0334 
0338 
035F 
0372 
0389 
03A3 
03AS 
03B3 



MOVE?: 



READ: 



COMP: 



GETNXT; 



MACLIB DSTACK 

SIZ 50 

TRT P 

TRT T 

PRN -(COMPUTATION OF TOOL 

LIT {INITIALIZE 

STO I 51=0 

TRF T {TURN CODE TRACE OFF 

LOOK FOR STARTING MOTION (NON ZERO VALUE) 

{READ A-D CONVERTER FOR NON ZERO 



5STACK MACHINE SIMULATION 
550 LEVEL STACK 
5TURN ON PRN TRACK 
5TURN ON CODE TRACE 

TRAVEL DISTANCE: 

INDEX 



STO 


X 


!HOLD TEMPORARILY 


VAL 


X 


{RELOAD FOR TEST 


LIT 


1 


5X GEO 1 TEST 


GEO 


READ 


5X GEO 1 ? 


BRN 


MOVE? 


{RETRY IF NOT 


PRN 


•(STORE f 


: IRST/NEXT VALUE> 


DMP 


X 




VAL 


X 


?LOAD FIRST/NEXT VALUE 


STO 


V.I 


5ST0RE TO THE ITH ELEMENT 


VAL 


I 


{INCREMENT I 


LIT 


1 




SUM 




51 + 1 


STO 


I 


;i=i+i 


LIT 





50. FOR GTR X TEST 


VAL 


X 


{ZERO VALUE READ? 


GEO 


COMP 


{COMPUTE DISTANCE IF 


RDM 





{READ ANOTHER DATA ITEM 


STO 


X 


5SAVE IT IN X 


BRN 


READ 


{TO STORE AND TEST 


PRN 


■(VALUES 


ARE LOADED) 


DMP 


V.10 




NOW 


COMPUTE DISTANCE TRAVELLED BY TOOL 


LIT 







DUP 




5TW0 ZEROES 


STO 


I 


;i=o 


STO 


TOTAL 


5T0TAL=0 


PRN 


•(COMPUTING NEXT INTERVAL) 


DMP 


I 




DMP 


TOTAL 




DMP 


<V,I>>2 




LIT 





{ZERO AT END 


VAL 


V.I 


5AT END? 


GEO 


ENDF 


50 GEO X(D? 



Listing 9-12. Program for Tool Travel Computation 
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NOT AT END OF INTERVAL, COMPUTE NEXT TRAPEZO 



03C0 


VAL 


V»I 




03CC 


VAL 


V > I 1 1 


iV(i) »y(i + n 


03DD 


SUM 




3V( I )+V( 1+1 > 


03DF 


LSR 


1 


;(V(i)+V(i+n/2 


03E6 


OAL 


TOTAL 


5READY TOTAL 


03EA 


SUM 




5T0TAL=T0TAL+TRAPEZ0ID 


03EC 


STO 


TOTAL 


;back to sum 


03EF 


VAL 


I 


;i=i+i 


03F2 


LIT 


1 




03FS 


SUM 






03F8 


STO 


I 


5BACK TO I 


03FB 


BRN 


GETNXT 




03FE ENDF: PRN 


<END OF 


COMPUTATION) 


0420 


DMP 


TOTAL 




0437 


UAL 


TOTAL 


".LOAD FOR D-A OUTPUT 


043A 


WRM 





5WRITE D-A PORT 


04BZ 


XIT 






> 
5 


DATA 


AREA 




11S4 


DCL 


I 


5INDEX 


1166 


DCL 


X 


TEMPORARY 


1168 


DCL 


0.100 


50EL0CITY VECTOR 


1230 


DCL 


TOTAL 


5T0TAL DISTANCE 






Listing 9-12. (continued) 



Following the MOVE? label, A-D port is read and examined for the first nonzero 
value. Each time the port is read, it is stored into the temporary variable X, then 
reloaded and examined for a zero value. Because GEQ is the only comparison oper- 
ator in the KDF-11 machine, the test is "1 greater than or equal to X." Thus, the 
branch is taken to READ whenever X is 1 or larger. 

Upon encountering the READ label, the value X (just read from port 0) is stored 
into V(I), where I is zero. The value of I is then incremented by loading I to the top 
of the KDF-11 stack, adding 1 (LIT 1, SUM), and then storing the sum back into I. 
After incrementing I, the program proceeds to check the end of the tool travel. X is 
loaded to the top of the stack, and the test greater than or equal to X is performed. 
If the condition is true, control transfers to the label COMP, where the analysis 
phase begins. Otherwise, port is read again, and the value is stored into the tem- 
porary X. Control then proceeds back to the READ label to store the next velocity 
and test for zero. 
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Before 100 intervals have elapsed, the RDM produces a zero value that is stored 
into X and subsequently stored into V(I), for the current value of I. Thus, when 
control arrives at the label COMP, the instantaneous velocities are stored in V, 
terminated by a zero. At this point, the analysis of these collected velocities can take 
place. 

The single function that takes place in the analysis section of Listing 9-12 is the 
computation of the distance traveled by the tool through this interval. Nachtflieger 
engineers have determined that it is sufficient to compute the distance traveled by the 
tool using the trapezoidal rule that approximates the actual distance by summing the 
average of each adjacent pair of velocities. The sums are formed as shown below: 

Vo + Vl , Vl+V 2 , , Vn-l+Vn 

- 1 - _|_ . . . _| _ 



where n is the last interval to sum. Thus, for example, if the velocity is constant at 
256 um/ms (which would not occur in practice), then 

Vi - V 2 = • • • = V n = 256 

The summing formula given above reduces to 256 * n. Given the preceding example, 
where n = 50 ms, this formula produces the value 1.280 mm, as given earlier. The 
velocity values are not usually constant, so the numerical integration given by the 
trapezoidal rule is used to obtain an approximation. 

The KDF-11 instructions shown in Listing 9-12 between the COMP and ENDF 
labels perform the numeric integration, given by the trapezoidal rule. The temporary 
I is used to index through the velocity vector V until the final zero value is encoun- 
tered. For each interval, the values of two adjacent velocities are summed and divided 
by two. Each result is then summed into TOTAL, where the values are accumulated 
until the final zero velocity is discovered. 

The opcode sequence immediately following COMP places a zero value at the top 
of the KDF-11 stack, then stores this value into both the index I and the accumulat- 
ing sum given by TOTAL. Ignoring the trace opcodes, the operations following 
GETNXT read the starting point of the next interval to process into the stack, using 
VAL V,I (value of V, indexed by I). If is greater than or equal to this value, then 
the computation is complete and control goes to the label ENDF. Otherwise, the 
value of V(I) is loaded to the KDF-11 stack, followed by the value of V(I+1). The 
loaded values are then summed (SUM) and divided by two (LSR 1), producing a 
value that remains in the KDF-11 stack. TOTAL is then loaded and added to this 
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partial sum, and the result is stored back to TOTAL. The index value I is then 
incremented to the next interval and processing continues back at the loop header 
GETNXT. 

Upon processing the final zero velocity, control reaches the ENDF label where the 
distance traveled is written to D-A output port zero. The output value is sent to 
external instrumentation, which processes the result and displays the distance trav- 
eled in a form that is readable by the tool operator. 

Debugging statements have been placed throughout the program. These can be 
used to trace the program execution. Listing 9-12 also contains TRT operators that 
have enabled trace code generation. Thus this program, although longer than the 
final production version, can be used to follow execution under CP/M. 

Listing 9-13 shows the execution of the program of Listing 9-12 under DDT. The 
messages printed at the debugging console are a result of the PRN opcodes distrib- 
uted throughout the original program that were enabled through the TRT P opcode. 
Further, the machine code trace was only enabled for the interval of two operation 
codes (LIT and STO) at the beginning. To test this program, simple A-D values were 
supplied at the console for the velocities: 

V = 100H, V! = 120H, V 2 = 100H, V 3 = 80H, V 4 = 

Upon detecting the final value, the trace of Listing 9-13 shows the first 10 values 
of V (the last 5 elements are garbage values), followed by a trace of the sum opera- 
tions for each interval. In each case, the pairs of values that are being added are 
displayed (using the DMP opcode), followed by their summed value, along with the 
running total. Upon completion of the distance computation, the value 320H is sent 
to the D-A output port and displayed at the console. 

After initial checks under CP/M, Nachtflieger programmers remove the TRT and 
TRF statements from the KDF-11 program and reassemble, producing only the abso- 
lute input/output instructions required for machine tool control. The resulting pro- 
gram, which produces much less code than the debugging version, is placed into the 
equipment for further testing and evaluation. 

Listing 9-14 also provides an example of the listing produced when all machine 
code operators are traced. Although the source program listing is not shown, it is 
identical to Listing 9-12 except that the TRF T opcode is removed. Because the 
complete trace is quite extensive, only a partial execution is shown in Listing 9-14. 
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(\>DDT IN TEG, HEX 
DDT VERS 1,4 
NEXT PC 
04G5 0000 
-G100 

COMPUTATION OF TOOL TRAVEL DISTANCE 

LIT 0139 0000 0F77 

STO 01D6 0000 0000 

A-D INPUT AT 4224 

A-D INPUT AT 4224 100 

STORE FIRST/NEXT VALUE 

X= 0100 

A-D INPUT AT 4224 120 

STORE FIRST/NEXT VALUE 

X= 0120 

A-D INPUT AT 4224 100 

STORE FIRST/NEXT VALUE 

X= 0100 

A-D INPUT AT 4224 80 

STORE FIRST/NEXT VALUE 

X= 0080 

A-D INPUT AT 4224 

STORE FIRST/NEXT VALUE 

X= 0000 

VALUES ARE LOADED 

V= 0100 0120 0100 0080 0000 3EC0 BAH C1C9 5EE1 5623 

COMPUTING NEXT INTERVAL 

1= 0000 

TOTAL= 0000 

Vil= 0100 0120 

COMPUTING NEXT INTERVAL 

1= 0001 

TOTAL= 0110 

V»I= 0120 0100 

COMPUTING NEXT INTERVAL 

1= 0002 

V»I= 0100 0080 

COMPUTING NEXT INTERVAL 

1= 0003 

TOTAL= 02E0 

V»I= 0080 0000 

COMPUTING NEXT INTERVAL 

1= 0004 

TOTAL= 0320 

V»I= 0000 3EC0 

END OF COMPUTATION 

TOTAL= 0320 

D-A OUTPUT AT 4240 0320 



Listing 9-13. Sample Execution of Distance Using DDT 
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&>ddt intestt hex 
DDT VERS 1.4 
NEXT PC 
0852 0000 
-3100 

COMPUTATION OF TOOL TRAVEL DISTANCE 

LIT 02BE 0000 CAB1 

STO 030B 0000 0000 

A-D INPUT AT 128 

RDM 0344 0000 0000 

STO 0358 0000 0000 

UAL 036E 0000 0000 

LIT 0384 0001 0000 

DIF 038D FFFF 0000 

GEO 03AF FFFF 0000 

A-D INPUT AT 128 S 

RDM 0344 OOOG 0000 

STO 0358 OOOG 0000 

VAL 03GE 0006 0000 

LIT 0384 0001 OOOG 

DIF 038D 0005 0000 

GEQ 03AF 0005 0000 

STORE FIRST/NEXT VALUE 

X= OOOG 

VAL 043F 0006 0000 

STO 045E 01GF 0000 

VAL 0473 0000 0000 

LIT 0488 0001 0000 

SUM 049D 0001 0000 

STO 04B2 0001 0001 

VAL 04C7 0006 0001 

A-D INPUT AT 128 

RDM 0501 0000 0006 

STO 0516 0000 0006 

LIT 052B 0001 0006 

DIF 0544 0005 0001 

GEO 055G 0005 0001 

STORE FIRST/NEXT VALUE 

X= 0000 

VAL 043F 0000 0001 

STO 045F 0171 0001 

VAL 0473 0001 0001 

LIT 0488 0001 0001 

SUM 048D 0002 0001 

STO 04B2 0002 0002 

VAL 04C7 0000 0002 

A-D INPUT AT 128 

RDM 0501 0000 0000 



Listing 9-14. Partial Listing of Distance with Full Trace 
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In summary, Nachtflieger MW derived several benefits from their emulation of the 
KDF series stack machines. First, there is very little cost involved in designing and 
altering their machine architecture. In fact, current prices for 8080 microcomputers 
might preclude the custom LSI version of the KDF-? machine. A second advantage of 
the KDF emulation is that the KDF programs are highly independent from the host 
processor. If a higher performance or less expensive processor becomes available to 
Nachtflieger, the existing programs can be used intact by changing only the macro 
definitions for each of the KDF opcodes and reassembling using MAC. 

Finally, machine emulation through macro defined operation codes offers a distinct 
advantage over interpretive approaches because each opcode translates to only a few 
host machine operations. Interpretive execution often involves ratios of 1000 to 20,000 
emulated instructions per host instruction; macro based opcodes are often in a ratio 
of less than 10 to 1. Further, interpretive processors usually require run-time support 
consisting of a predefined general purpose subroutine package that is included for 
each and every program. For a wide variety of microcomputer applications, machine 
emulation through macro defined opcodes offers distinct advantages over alternative 
approaches. 



9.3 Program Control Structures 

Macro facilities can provide program control statements that resemble those found 
in many high-level languages. In general, program control statements allow Boolean 
tests and conditional branching based on the outcome of the Boolean test. Further, 
label names usually provided by you as the destination of a branch are automatically 
generated for the particular statement. 

The following paragraphs discuss three typical control statements that allow simple 
conditional grouping (WHEN-ENDW), controlled iteration (DO-ENDDO), and case 
selection (SELECT-ENDSEL). All three statements are program control facilities that 
allow well-structured programming, resulting in programs that are easier to write, 
debug, and maintain. 

Two libraries are first introduced as a foundation for the discussion. The I/O 
library shown in Listing 9-15 allows simple character input operations along with 
full message output. The READ macro accepts a single character from the console 
keyboard and stores this character into the variable given by the parameter VAR. 
The WRITE macro shown in Listing 9-15 takes an ASCII message as a parameter 
and sends this message to the console output device preceded by a carriage return 
line-feed sequence. These simple I/O macros are stored in the disk in the file SIM- 
PIO.LIB and are used in the examples that illustrate the control structures. 
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The second library used in the control structure examples is given in Listing 9-16. 
Collectively, these macros define a number of Boolean operations that are performed 
on 8 -bit operands, providing the basic relational operations on unsigned integer values, 
including: 

LSS less than 

LEQ less than or equal to 

EQL equal to 

NEQ not equal to 

GEQ greater than or equal to 

GTR greater than 

In all cases, the macros accept three actual parameters. The parameters consist of 
two data values involved in the test (X and Y), along with a program label that 
receives control if the Boolean test produces a true value (TL). The first operand X 
can be a labeled memory location containing an 8 -bit value, and Y can be either a 
labeled 8-bit location or a literal numeric value. If the first operand X is not supplied, 
then the value to be tested is assumed to exist in the 8080 accumulator when the 
macro is entered. Thus, for example, the macro invocation 

LSS ALPHA ,BETA tTRUECASE 

compares the values stored at the labeled memory locations ALPHA and BETA, 
defined by a DS or DB statement, and transfers to the program step labeled by 
TRUECASE if ALPHA contains a value less than the value stored at BETA. The 
invocation 

LSS *BETA jTRUECASE 

is similar, but it compares the contents of the 8080 accumulator with the value 
stored at BETA. Finally, the invocation 

LSS ALPHA ,34>TRUECASE 

compares ALPHA with the literal value 34 in the relational test. 
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The macro TEST? is used throughout the macro library to construct the relational 
test by first loading the initial operand X, if necessary. The second operand type is 
then examined by executing an IRPC within the TEST? macro of Listing 9-16. This 
extracts the first character of the Y operand. This first character must be either 
numeric or alphabetic. If numeric, then the literal value is subtracted from the accu- 
mulator, setting the 8080 condition codes. If the first character of Y is nonnumeric, 
then the value is assumed to reside in memory. In this case, the HL registers are set 
to the Y operand and the value at Y is subtracted from the accumulator value. In 
any case, the 8080 condition codes are set as a result of the subtraction operation. 
These condition codes are then used in the individual macros to produce conditional 
jumps to the destination labels. These macros are collectively stored on the disk in a 
file named COMPARE.LIB for use in examples that follow. 



Macro library for simple i/o 



bdos 


equ 


0005 h 


ibdos entry 


conin 


equ 


1 


jconsole input function 


ms Sout 


eiu 


9 


Sprint message til $ 


c r 


equ 


Odh 


Jcarriasfe return 


If 


equ 


Oah 


1 1 i n e feed 


read 


mac ro 


ijar 




5 5 


read a sinsfle character into u a r 




mu i 


c tconin 


•console input function 




call 


bdos 


5characte r is in a 




sta 


Mar 






endm 






write 


mac ro 


MS S 




5 5 


write 


message to 


console 




local 


ms sl »pws sf 




JfrtP 


PMS 3 




His 31 : 


db 


cr tlf 


5 5 1 ead in 3 crlf 




db 


'&MSG' 


iiinline message 




db 


'%' 


5 5itiessa3e te rminato r 


pmsS: 


mui 


C fMSSOUt 


i 5 p r i n t message til $ 




lxi 


d » m s 3 1 






call 


bdos 






endm 







Listing 9-15. Simple I/O Macro Library 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 147 



9.3 Program Control Structures Programmer's Utilities Guide 



test? macro x » v 

55 utility macro to Generate condition codes 

if not nul x ! 5 then load x 

Ida x 55 assumed to be in memory 

endif 

i rpc ?y»y 5»y may be constant operand 
tdis? set '&?Y'-'0' iifirst char disit? 

exitm 55-stop irpc after first char 

endm 

if tdis? <= 9 ! 5 y numeric? 

sui y jjyes* so sub immediate 

e lse 

lxi h»y 55y not n urn eric- 

sub m !iso sub from memory 

endm 
5 
lss macro x t y » 1 1 

x lss than y test t 

transfer to tl (true label) if true* 

continue if test is false 

test? x >y 5iset condition codes 

Jc tl 

endm 



leq 



eql 



mac ro 


x » y 1 1 1 






x less 


than or equal 


toy 


test 


lss 


x »y »t 1 






Jz 


tl 






endm 








mac ro 


x >y >tl 






x equal 


to y test 






test? 


X lY 






Jz 


tl 






endm 









macro x »y »t 1 

x not equal to y test 

test? x»y 

Jnz tl 

endm 



Listing 9-16. Macro Library for Simple Comparison Operations 
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St r 



fl: 



Mac ro 


x >y »t 1 




x Greater than 


or equal to y test 


test? 


X >Y 




Jnc 


tl 




en dm 






mac ro 


x >y »t 1 




x Greater than 


y test 


local 


fl 


iifalse label 


test? 


x >y 




Jc 


fl 




dc r 


a 




Jnc 


tl 




endm 







Listing 9-16. (continued) 



Listings 9- 17a and 9- 17b show an example of a program that uses both the SIM- 
PIO and COMPARE libraries. This program successively reads console characters 
and print messages based on the character typed. The program begins by sending the 
sign-on message at the label CYCLE. A character is then read and stored into X, 
using the READ macro. The LSS test determines whether lower- to upper-case trans- 
lation is required, assuming the input is alphabetic. If X is numerically less than 61H, 
the value of a lower-case A, then control transfers to the label NOTRAN. Otherwise, 
the character is loaded to the accumulator, the lower-case bit is stripped from the 
character, and it is replaced in memory. Following the label NOTRAN, the character 
is compared with the letters A, B, C, and D. In each case, a message is typed 
corresponding to each letter. If one of these four letters cannot be found, the message 
at ERROR is typed. 
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0100 



ORG 100H 

MACLIB SIMPIO 5SIMPLE 10 LIBRARY 

MACLIB COMPARE 5C0MPARIS0N OPERATORS 



0100 
012B 

0133 



CYCLE: WRITE <TYPE A CHARACTER FROM A TO D > 

READ X 
5 TEST FOR LOWER CASE ALPHABETIC 

LSS X,G1H.N0TRAN 
5 ARRIVE HERE IF X IS GREATER OR EQUAL TO 
5 A LOWER CASE A (=S1H)» TRANSLATE 



013B 


3A1102 




LDA 


X 


013E 


EB5F 




ANI 


5FH iCLEAR LOWER Ci 


0140 


321102 


NOTRAN 


STA 


X 5ST0RE BACK TO 






5 


NOW CHECK CASES 


0143 




> 


NEQ 


X»I'A' >NOTA 


014B 






WRITE 


<YOU TYPED AN A> 


01S7 


C30001 




JMP 


CYCLE 


01SA 




NOTA: 


NEQ 


X,X'B'»NOTB 


0172 






WRITE 


<YOU TYPED A B> 


018D 


C30001 




JMP 


CYCLE 


0190 




NOTB: 


NEQ 


X>X'C »NOTC 


0198 






WRITE 


<YOU TYPED A C> 


01B3 


C30001 




JMP 


CYCLE 


01BB 




i 
NOTC: 


NEQ 


X»X'D' » ERROR 


01BE 






WRITE 


<YOU TYPED A D> 


01D9 






WRITE 


<BYE-!> 


01EB 


C9 




RET 




01EC 




> 
ERROR: 


WRITE 


<NOT AN A» B» C» OR D> 


020E 


C30001 




JMP 


CYCLE 


0211 




5 

X: 


DS 


1 5TEMP FOR CHAR 


0212 






END 





Listing 9-1 7a. Single Character Processing using COMPARE 
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In comparing each letter, the macro NEQ starts with the first argument corre- 
sponding to the character typed at the console (X) ; the second argument corresponds 
to the letter to match. The % operator in each case produces the numeric value of 
the character. This is necessary because the TEST? macro expects either a number or 
a label value in the second argument position. The program processes characters 
until a D is typed when it returns to the Console Command Processor. The intention 
here is to show the use of Boolean tests used by the control structure macros that 
follow. 

Listing 9- 17b shows a partial expansion of the macros given in the previous exam- 
ple. The first message expansion is shown, along with the READ and NEQ macros. 
The listing has been abstracted, however, and does not show the macro library 
statements or the remainder of the program following the NOTA label. 
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CYCLE: 


WRITE 


<TYPE A CHARACTER FROM A TO D > 


0100+C32301 




JMP 


??0002 


0103+ODOA 


??0001 


: 


DB CR.LF 


0105+5459504520 


i 


DB 


'TYPE A CHARACTER FROM A TO D ' 


0122+24 




DB 


'$' 


0123+OE09 


??0002 


: 


MVI CMSGOUT 


0125+110301 




LXI 


D»??0001 


0128+CD0500 




CALL 


BDOS 






READ 


X 


012B+OE01 




MVI 


CCONIN .CONSOLE INPUT FUNCTION 


012D+CD0500 




CALL 


BDOS .CHARACTER IS IN A 


0130+321102 




STA 


. X 


5 




TEST FOR LOWER CASE ALPHABETIC 






LSS 


X»S1H»N0TRAN 


0133+3A1102 




LDA 


X 


013B+DGG1 




SUI 


G1H 


0138+DA4301 




JC 


NOTRAN 


5 




ARRIVE 


HERE IF X IS GREATER OR EQUAL TO 


5 




A LOWER 


CASE A (=B1H) , TRANSLATE 


013B 3A1102 




LDA 


X 


013E EG5F 




ANI 


5FH 5CLEAR LOWER CASE BIT 


0140 321102 




STA 


X 5ST0RE BACK TO X 



NOTRAN; 



NOW CHECK CASES 





NEO 


X»I'A' ,NOTA 


0143+3A1102 


LDA 


X 


014G+D641 


SUI 


65 


0148+C26A01 


JNZ 


NOTA 




WRITE 


<YOU TYPED AN A> 


014B+C35F01 


JMP 


??0004 


014E+ODOA ??0003 


: 


DB CR»LF 


0150+594F552054 


DB 


'YOU TYPED AN A' 


015E+24 


DB 


'$' 


015F+OE09 ??0004 


: 


MVI CMSGOUT 


0161+114E01 


LXI 


D.??0003 


01G4+CD0500 


CALL 


BDOS 


0167 C30001 


JMP 


CYCLE 


> 

NOTA: 


NEO 


XfX'B' »NOTB 



Listing 9- 17b. Partial Trace of Listing 9-1 7a with Macro Generation 
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The macro library shown in Listing 9-18, called NCOMPARE, expands upon the 
basic relational macros by allowing a false branch option. Each macro accepts four 
arguments: the X and Y operands, as before, a true label (TL), and a false label (FL). 
It is assumed that either the TL or FL is supplied in any invocation of a relational 
operator, but not both. If the TL is supplied, then the branch is taken if the relational 
operator produces a true result. Conversely, if the TL label is absent but the FL label 
is supplied, then the branch to FL is taken if the relational operation produces a false 
result. Thus, NCOMPARE expands upon the COMPARE library by allowing all of 
the relational operation and their negations. Using the NCOMPARE library, for 
example, the macro invocation 

LSS X»20» »FALSELAB 

branches to the label FALSELAB if X is not less than the value 20. The negation 
operations are accomplished within the NCOMPARE library by first testing for a 
null TL operand and, if empty, the relational operation is reversed by invoking the 
appropriate negated macro. For example, the LSS macro in Listing 9-18 invokes the 
GEQ macro, which is equivalent to 'not LSS' when the TL argument is empty and 
supplies the FL argument to LSS as the TL label to GEQ. These negated relational 
forms are used within the control structures described below. 



5 macro library for 8-bit comparison operation 

5 

test? mac ro x »y 

5 5 utility macro to Generate condition codes 

if notnulx 5 J then load x 

Ida x 5!x assumed to be in memory 

endif 

irpc ?y »y 55y may be constant operand 
tdis? set '&?Y'-'0' 55first char disit? 

exitm 55stop irpc after first char 

endm 

if tdi sf? <= 9 5 iy numeric? 

sui y 55yes> so sub immediate 

e lse 

lxi h»y 55 y not n urn eric 

sub m 5 5 s o sub from memory 

endm 



Listing 9-18. Expanded NCOMPARE Comparison Operators 
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lss wac ro x »y >tl »f 1 

x lss than y test * 

if tl is present* assume true test 

if tl is absent* then invert test 

if nul tl 

3eq x »y >t 1 

else 

test? x»y iiset condition codes 

Jc 1 1 

endm 
! 

leq mac ro x iy >tl if 1 
5! x less than or equal to y test 

if nul tl 

tfeq x »y if 1 

else 

lss x »y >tl 

Jz tl 

endm 
eql mac ro x »y >tl >f 1 
i 5 x equal to y test 

if nul tl 

neq x iy if 1 

else 

test? x »y 

Jz tl 

endm 
5 

neq mac ro x >y »tl >f 1 
5 5 x not equal to y test 

if nul tl 

eql x iy if 1 

else 

test? x iy 

Jnz tl 

endm 
! 

3eq mac ro x >y »tl if 1 
5! x Greater than or equal to y test 

if nul tl 

lss x IY if 1 

else 

test? x »y 

Jnc tl 

endm 



Listing 9-18. (continued) 
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Str 



<ffl 



«ac ro x »y *t 1 »f 1 

x Greater than y test 



if 


nul 


tl 




leq 


x >y : 


► f 1 




else 








local 


an 




5 jf alse label 


test? 


x »y 






Jc 


Sfl 






dc r 


a 






Jnc 


tl 






en dm 






Listing 9-18 



(continued) 



Listing 9- 19a is an example of the use of the NCOMPARE library within a pro- 
gram. This program is similar to the previous example, but instead checks to ensure 
that alphabetic translation occurs only within the proper range of lower-case letters. 
Following the label CYCLE, the character read from the console is compared with a 
lower-case a, using the % operation to produce equivalent decimal value 97. Because 
the negated form of GEQ is used here, the label NOTRAN receives control if X is 
not greater than or equal to %'a'. If X is greater than or equal to %a, program flow 
continues to the next test in sequence where X is compared with a lower-case z 
(%'z'= decimal 122). In this case, the normal form of GTR is used. Control trans- 
fers to NOTRAN if X is greater than %'z', which is above the range of lower-case 
alphabetics. If X is between %'a' and %'z', the character is changed to upper-case, 
as before, by removing the lower-case bit and replacing X in memory. Note that the 
indentation levels between the GEQ and GTR operations are included for readability 
of the program. 
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Listing 9- 19b shows the GEQ-GTR section of the program of Listing 9- 19a with 
full macro trace enabled. (See Section 10.) The trace in this listing shows the transi- 
tion from GEQ to the LSS operator, substituting the FL label in place of the TL 
label. Again, the macro library statements are not shown, and the listing following 
the NOTRAN label is not present. 



0100 



0100 
012B 

0133 

013B 

0147 3A1D02 
014A E65F 
014C 321D02 



ORG 100H 

MACLIB SIMPI0 .SIMPLE 10 LIBRARY 

MACLIB NCOMPAREiCOMPARISON OPERATORS 
5 
CYCLE: WRITE <TYPE A CHARACTER FROM A TO D > 

READ X 
5 TEST FOR LOWER CASE ALPHABETIC 

GEO XtX'a' » tNOTRAN iBRANCH ON FALSE 
5 X IS GREATER OR EQUAL TO LOWER CASE A 
GTR X#Z'z'»NOTRAN 



LDA 


X 




ANI 


5FH 


5UPPER CASE 


STA 


X 


5BACK TO X 



NOTRANs 



NOW CHECK CASES 



014F 






NEC 


X.I 'A' >N0TA 


0157 






WRITE 


<Y0U TYPED AN A> 


0173 


C30001 




JMP 


CYCLE 


0176 




NOTA: 


NEO 


X.I'B' ,N0TB 


017E 






WRITE 


<Y0U TYPED A B> 


0199 


C30001 




JMP 


CYCLE 


019C 




NOTB: 


NEO 


X.X'C >N0TC 


01A4 






WRITE 


<Y0U TYPED A C> 


01BF 


C30001 




JMP 


CYCLE 


01C2 




5 

NOTC: 


NEO 


X»X'D' »ERR0R 


01CA 






WRITE 


<Y0U TYPED A D> 


01E5 






WRITE 


<BYE'!> 


01F7 


C9 




RET 




01F8 




» 

ERROR: 


WRITE 


(NOT AN A» Bi C» OR D> 


021A 


C30001 




JMP 


CYCLE 


021D 




i 
X: 


DS 


1 5TEMP FOR CHAR 


021E 






END 





Listing 9-19a. Sample Program using NCOMPARE Library 
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TEST FOR LOWER CASE ALPHABETIC 



0133+3A1D02 

+ 
+ 
+ 
+ 
+ 
0009+* 



0136+D6B1 



0138+DA4F01 

+ 



013B+3A1D02 

+ 



+ 
0001+# 





GEO 


X.Z'a' ..NOTRAN 5BRANCH ON 1 




IF 


NUL 




LSS 


X. 97, NOTRAN 




IF 


NUL NOTRAN 




GEO 


X.97, 




ELSE 






TEST? 


X.97 




IF 


NOT NUL X 




LDA 


X 




ENDIF 






IRPC 


?Y.97 


TDIG? 


SET 

EXITM 

ENDM 


'&?Y'-'0' 


TDIG? 


SET 
EXITM 


'9'-'0' 




IF 


TDIG? <= 9 




SUI 


97 




ELSE 






LXI 


H»97 




SUB 


M 




ENDM 






JC 


NOTRAN 




ENDM 






ELSE 






TEST? 


X>97 




JNC 






ENDM 




5 


X IS GREATER OR EQUAL TO LOWER CASE 






GTR Xtl'z' »N0TRAN 




IF 


NUL NOTRAN 




LEO 


Xtl22» 




ELSE 






LOCAL 


GFL 




TEST? 


X.122 




IF 


NOT NUL X 




LDA 


X 




ENDIF 






IRPC 


?Y,122 


TDIG? 


SET 

EXITM 

ENDM 


'&?Y'-'0' 


TDIG? 


SET 
EXITM 


' 1 ' - ' ' 




IF 


TDIG? <= 9 


isting 9- 19b. 


Segment of Listing 9- 19a with + M ( 
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013E+DG7A 




SUI 


122 




+ 




ELSE 






+ 




LXI 


H»122 




+ 




SUB 


M 




+ 




ENDM 






0140+DA4701 




JC 


??0003 




0143+3D 




DCR 


A 




0144+D24F01 




JNC 


NOTRAN 




+ 


??0003 


: 


ENDM 




0147 3A1D02 






LDA 


X 


014A EB5F 






ANI 


5FH 5UPPER CASE 


014C 321D02 


5 

NOTRAN 


: 


STA 


X 5 BACK TO X 






Listing 9-19b. 


(continued) 



Given the SIMPIO and NCOMPARE libraries, it is now possible to define the first 
complete control structure, called the WHEN-ENDW group. The form of the group 
is 

WHEN condition 
statement- 1 
statement-2 

statement-n 
ENDW 

where condition is a relational expression taking one of the forms 

id,rel,id id,rel,number ,rel,id ,rel,number 

and id is an identifier; rel is a relational operator (LSS, LEQ, EQL, NEQ, GEQ, 
GTR), and number is a literal numeric value. Similar in form to the arguments of the 
individual relational operators of the COMPARE library, the last two forms shown 
above assume the first argument is present in the 8080 accumulator. The condition 
following the WHEN is evaluated as a relational expression, according to the rules 
stated with the COMPARE library. If the condition produces a true result, then 
statement- 1 through statement-n are executed. Otherwise, control transfers to the 
statement following the ENDW. Nested WHEN-ENDW groups are allowed when 
they take the form: 
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WHEN . . . 

WHEN . . . 

WHEN . . . 

ENDW 

ENDW 

ENDW 

to arbitrary levels, where the ellipses represent interspersed statements. Because of 
the simplified implementation, nested parallel WHEN-ENDW groups are disallowed 
when they take the form: 

WHEN . . . 

WHEN . . . 

ENDW 

WHEN . . . 

ENDW 

ENDW 

The implementation of the WHEN-ENDW group is based upon macros that count 
WHEN-ENDW groups and generate branches and labels at the proper levels in the 
structure. 

Listing 9-20 shows the WHEN macro library, consisting of four macros: 

GENWTST (generate WHEN test) 

GENLAB (generate label) 

WHEN (beginning of WHEN group) 

ENDW (end of WHEN group) 
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These macros, in turn, use the macros in the NCOMPARE library shown previously 
and thus are assumed to exist in the user's program as a result of a MACLIB 
NCOMPARE statement. Label generation is based on the WCNT (WHEN count) 
and WLEV (WHEN level) counters. WCNT is incremented each time a WHEN is 
encountered, and WLEV keeps track of the number of WHENs that have occurred 
without corresponding ENDWs. 

Upon encountering the first WHEN, the WCNT and WLEV counters are set to 
zero, and the WHEN macro is redefined to generate the first WHEN test by invoking 
GENWTST, using the relation R, operands X and Y, and WHEN counter WCNT. 
The value of WCNT is passed to GENWTST rather than the characters WCNT 
themselves. Thus, at the first invocation of GENWTST, the dummy argument NUM 
has the value 0. The first argument to GENWTST, called TST, corresponds to a 
relational operation (LSS through GTR) and thus is invoked automatically within the 
body of GENWTST, using the negated form of the relational because the TL argu- 
ment is empty. 

Again referring to the body of the GENWTST macro in Listing 9-20, the last 
argument, corresponding to the false label of the relational operation, is the con- 
structed label ENDW&num, where num has the value initially, and successively 
larger values on later invocations. Each time GENWTST is invoked, it generates a 
relational test and a branch on false to a generated label. It is the responsibility of 
the ENDW macro to produce the appropriate balanced label when encountered in 
the program. 

In the body of the WHEN macro in Listing 9-20, the WLEV level counter is set to 
the current WCNT, and the WCNT is incremented in preparation for the next WHEN 
statement. Similar to nearly all macros that redefine themselves, the outer macro 
definition of WHEN invokes the newly created WHEN macro before exit. 

Upon encountering the ENDW statement in the source program, the ENDW macro 
first invokes GENLAB to generate the appropriate ENDW label. The first argument 
to GENLAB is the label prefix ENDW; the second argument is the evaluated param- 
eter %WLEV corresponding to the current ENDW label. If only one WHEN state- 
ment is encountered, for example, the value of WLEV is zero, and thus GENLAB 
produces the label END WO, which is the destination of the earlier branch generated 
by an invocation of GENWTST. Following the invocation of GENLAB, WLEV is 
decremented to account for the fact that one more destination label has been resolved. 
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5 macro library for "when" construct 

5 

i label Sene rat o rs 

Senwtst macro tst >x iv mum 

55 Generate a "when" test (negated form)» 

ii irmoKe macro "tst" with parameters 

ii x tv with Jump to endw & nun 

tst my i tendw&num 

endw 
i 

Sen lab macro lab mum 
i 5 produce the label "lab" & " n u m " 
1 abknum : 

e n d m 

i 

i "when" macros for start and end 

i 

when macro x v > r e 1 > y v 

ii initialize counters first time 

went set 5 5 number of whens 

when macro xtrtv 

Senwtst DX»y »Zwcnt 
w 1 e y set went iinext endw to Generate 
went set wcnt + 1 i in umber of i"when"s 

e n d m 

when x v t r e 1 > y v 

e n d m 
i 

endw macro 
i i Generate the e n d i n S code for a "when" 

Sen lab endwt'Xwley 
wley set wley-1 5 5 count current ley el down 
i i w 1 e t.i must not So below (not c h e c K e d ) 

endw 



Listing 9-20. Macro Library for the WHEN Statement 
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As an example of the use of WHEN-ENDW, Listing 9-2 la shows a sample pro- 
gram that resembles the previous character scanning function, but uses the WHEN 
group in place of simple tests and branches. As before, a single character is read 
from the console and first tested for possible case conversion. The statement WHEN 
X,GEQ,61H causes the three statements that follow to execute only when X is 
greater than or equal to 61H (lower-case a). Further, the four WHEN groups that 
follow test for the specific characters A, B, C, or D. If an A is typed, the correspond- 
ing WHEN group executes, and control transfers back to the CYCLE label where 
another character is read from the console. If the letter D is typed, the program 
responds with two messages and returns to the console command processor. 

Listing 9-2 lb shows the same program with full macro trace enabled. This portion 
of the program shows macro processing for the first WHEN-ENDW group only, 
although the remaining groups are processed in a similar fashion. It is a worthwhile 
exercise to determine that the nesting rules for WHEN groups are properly stated, 
and that the restriction on nested parallel groups is necessary. 



0100 




ORG 


100H 






MACLIB 


SIMPI0 5SIMPLE 10 LIBRARY 






MACLIB 


NC0MPARE!EXPANDED COMPARE ops 






MACLIB 


WHEN 5WHEN CONSTRUCT 


0100 




CYCLE: WRITE 


<TYPE A CHARACTER FROM A TO D 


012B 




READ 


X 






? TEST FOR LOWER CASE ALPHABETIC 


0133 




WHEN 


X,GEQt61H 


013B 


3A1102 


LDA 


X 


013E 


EB5F 


ANI 


5FH iCLEAR LOWER CASE BIT 


0140 


321102 


STA 


X 5ST0RE BACK TO X 


0143 




ENDW 








5 NOW CHECK CASES 


0143 




WHEN 


XtEQL»X'A' 


014B 




WRITE 


<Y0U TYPED AN A> 


0167 


C30001 


JMP 


CYCLE 


016A 




ENDW 




016A 




i 

WHEN 


X»E0L»X'B' 


0172 




WRITE 


<Y0U TYPED A BI- 


018D 


C30001 


JMP 


CYCLE 


0190 




ENDW 





Listing 9-2 la. Sample WHEN Program with — M in Effect 
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0190 




WHEN 


X»EOL»X'C 








0198 




WRITE 


<YOU TYPED 


A 


C> 




01B3 


C30001 


JMP 


CYCLE 








01B6 




ENDW 










01BG 


i 


WHEN 


X»EQL»I 'D 








01BE 




WRITE 


<YOU TYPED 


A 


D> 




01D9 




WRITE 


<BYE'!> 








01EB 


C9 


RET 










01EC 




ENDW 










01EC 


> 


WRITE 


<NOT AN A, 


B 


» Ci 


OR D> 


020E 


C30001 


JMP 


CYCLE 









0211 



DS 



5TEMP FOR CHARACTER 



Listing 9-2 la. (continued) 



0000+* 

+ 
+ 

+ 
+ 
+ 
+ 



TEST FOR LOWER CASE ALPHABETIC 

WHEN X.GE0.G1H 

WCNT SET 

WHEN MACRO X»R.Y 

GENWTST R»X»Y*ZWCNT 

WLEV SET WCNT 

WCNT SET WCNT+1 

ENDM 

WHEN X»GEQ»S1H 

GENWTST GEQiX»61H»XHCNT 



+ 




GEO 


X.B1H»,ENDW 


+ 




IF 


NUL 


+ 




LSS 


X»B1H»ENDW0 


+ 




IF 


NUL ENDWO 


+ 




GEO 


X.B1H. 


+ 




ELSE 




+ 




TEST? 


X»G1H 


+ 




IF 


NOT NUL X 


0133+3A1102 




LDA 


X 


+ 




ENDIF 




+ 




IRPC 


?Y»S1H 


+ 


TDIG? 


SET 


'ScTY'-'O' 


+ 




EXITM 




+ 




ENDM 




0006+# 


TDIG? 


SET 


'B'-'O' 


+ 




EXITM 




+ 




IF 


TDIG? <= 9 



Listing 9-2 lb. Partial Listing of Listing 9-2 la with +M Option 
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013B+DGG1 




BUI 


G1H 




+ 




ELSE 






+ 




LXI 


H.G1H 




+ 




SUB 


M 




+ 




ENDM 






0138+DA4301 




JC 


ENDWO 




+ 




ENDM 






+ 




ELSE 






+ 




TEST? 


X>G1H 




+ 




JNC 






+ 




ENDM 






+ 




ENDM 






0000+* 


WLEM 


SET 


WCNT 




0001+* 


WCNT 


SET 


WCNT+1 




+ 




ENDM 






+ 




ENDM 






013B 3A1102 




LDA 


X 




013E E65F 




ANI 


5FH 


5CLEAR LOWER CASE BIT 


0140 321102 




STA 
ENDM 


X 


5ST0RE BACK TO X 



Listing 9-2 lb. (continued) 



A second control structure, called the DOWHILE-ENDDO group, takes the gen- 
eral form: 



DOWHILE 
statement- 1 
statement-2 



condition 



statement-n 
ENDDO 

where the condition and nesting rules are identical to the WHEN-ENDW group. The 
DOWHILE group is similar in concept to the WHEN group, except that statements 
1 through n execute repetitively as long as the condition remains true. That is, the 
condition is evaluated when the DOWHILE is encountered in normal program flow. 
If the condition produces a false value, then control transfers to the statement follow- 
ing the ENDDO. Otherwise, the statements within the group execute until the ENDDO 
is reached. Upon encountering the ENDDO, control transfers back to the DOWHILE, 
and the condition is evaluated again. Iteration continues through the group until the 
condition produces a false value. 



164 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 9.3 Program Control Structures 

The macro library for the DOWHILE group is shown in Listing 9-22. The 
DOWHILE statement invokes the relational operator macros to produce the proper 
sequence of tests and branches. Upon encountering the ENDDO, the proper label 
and jump sequence is again generated. The only essential difference in the DOWHILE 
and WHEN groups is that the location of the DOWHILE test must be labeled, and 
a JMP instruction must be generated to this label at the end of each group. 

! macro library for "dowhile" construct 

! 

Sendtst macro tst»x»y>num 

5 5 Senerate a "dowhile" test 

tst x *y » >enddknum 

endm 
5 

dendlab macro labtnum 
55 produce the label lab & num 
55 for dowhile entry or exit 
lab&num: 

endm 
5 

SendJmp macro num 
5! Generate Jump to dowhile test 

Jmp dtest&num 

endm 
5 

dowhile macro xu»rel»yv 
55 initialize counter 
docnt set 5 number of do whiles 
5 5 

dowhi le mac ro x > r >y 
5! Generate the dowhile entry 

Sendlab d t e s t » X docnt 
5! Generate the conditional test 

Sendtst rfXfy>%docnt 
doleu set docnt 55next endd to Generate 
docnt set docnt+1 

endm 

dowhi le xu > rel »yu 

endm 

end do macro 

Generate the Jump to the test 

SendJmpIdoleu 

Generate the end of a dowhile 

3 e n d 1 a b enddtXdoleu 
do ley set dolev-1 

endm 

Listing 9-22. Macro Library for the DOWHILE Statement 
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In Listing 9-22, GENDTST (generate DOWHILE test), GENDLAB (generate 
DOWHILE label), and GENDJMP (generate DOWHILE jump) are all label genera- 
tors used in the macros that follow. Similar to the WHEN macro, DOWHILE uses 
the counters DOCNT and DOLEV to keep track of the number of DOWHILE 
groups encountered along with the current DOWHILE level, corresponding to the 
number of unmatched DOWHILEs. The DOWHILE macro first generates the entry 
label DTESTn, where n is the DOWHILE count. The conditional test is then gener- 
ated, similar to the WHEN macro, with a branch on false condition to the ENDDn 
label that is eventually generated by the ENDDO macro. Finally, the DOWHILE 
macro increments the DOCNT counter in preparation for the next group. 

The ENDDO macro in Listing 9-22 first generates the JMP instruction back to the 
DOWHILE test, using the GENDLAB utility macro, and then produces the ENDDn 
label that becomes the target of the jump on false condition. The form of the expanded 
macros for one nested level thus becomes: 

DTESTO: 

conditional Jump to ENDDO 

DTEST1: 

conditional Jump to ENDD 1 

♦ ♦ ♦ 

JMP DTEST1 
♦ ♦ ♦ 
ENDD1 
JMP DTESTO 

Listing 9-23a shows an example of a program that uses the DOWHILE group. 
Although this program differs slightly from the previous examples, the principal 
function is the same: a STOP character is first read from the console, followed by a 
group of statements that repetitively execute in search of the STOP character. Two 
DOWHILE groups occur within the program. The first group checks each character 
typed (X) to see if it matches the STOP character. If not (DOWHILE X,NEQ,STOP), 
the statements up through the matching ENDDO are processed. If the value of X is 
the character A, then the message YOU TYPED AN A is sent to the console. Other- 
wise, the message NOT AN A is typed, followed by a check to see if the STOP 
character was typed. If so, the messages STOP CHARACTER and BYE! appear at 
the console. Control continues through the ENDWs to the ENDDO and back to the 
DOWHILE header. The DOWHILE X,NEQ,STOP produces a false condition, and 
control transfers to the XRA A instruction following the ENDDO. 
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0100 



ORG 100H 

MACLIB SIMPIO iSIMPLE 10 LIBRARY 

MACLIB NC0MPARE5EXPANDED COMPARE OPS 

MACLIB WHEN 5WHEN CONSTRUCT 

MACLIB DOWHILE 5D0WHILE STATEMENT 



0100 
0127 



WRITE <TYPE THE STOP CHARACTER: 

READ STOP 

X = FOR THE FIRST LOOP 



> 



012F 
0139 
0159 



DOWHILE X.NEQtSTOP 5L00K FOR STOP CHARACTER 
WRITE <TYPE A CHARACTER: > 
READ X 



0161 
0169 
0185 



WHEN 

WRITE 

ENDW 



X»EQL,X'A' 

<YOU TYPED AN A> 



0185 
018D 
01A3 
01AD 
01C9 
01DB 
01DB 
01DB 



WHEN 
WRITE 



ENDW 
ENDDO 



XtNEQ»Z'A' 

<NOT AN A> 

WHEN 

WRITE 

WRITE 

ENDW 



X.EOL»STOP 
<STOP CHARACTER> 
<BYE'!> 



01DE AF 
01DF 320002 
01E2 
01EA 

01F8 210002 
01FB 34 
01FC 
01FF C9 



CLEAR THE SCREEN (23 CRLF'S) 



XRA 
STA 



iX = 



DOWHILE X»LSS>23 
WRITE <> 



LXI 
INR 
ENDDO 
RET 



H»X 
M 



5X=X+1 



0200 00 
0201 



X: 
STOP: 



DB 
DS 



5EXECUTES "DOWHILE" FIRST TIME 
jSTOP CHARACTER 



Listing 9-23 a. An Example Using the DOWHILE Statement 
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5 


CLEAR 


THE SCREEN 


(23 CRLF'S) 


01DE AF 




XRA 




A 




01DF 320002 




STA 




X 


;x=o 






DOWHILE 


X»LSS»23 




01E2+3A0002 




LDA 




X 




01E5+D617 




SUI 




23 




01E7+D2FF01 




JNC 
WRITE 




ENDDl 
<> 




01EA+C3F001 




JMP 




??0014 




01ED+0D0A 


??0013 


s 




DB 1 


:r»lf 


01EF+24 




DB 




'$' 




01F0+0E09 


??0014 


: 




MVI 1 


:»msgout 


01F2+11ED01 




LXI 




D»??0013 




01F5+CD0500 




CALL 




BDOS 




01F8 210002 




LXI 




H»X 




01FB 34 




INR 
ENDDO 




M 


;x=x+i 


01FC+C3E201 




JMP 




DTEST1 




01FF C9 




RET 









Listing 9-23b. Partial Listing of Listing 9-23a 
with Macro Generation 



In Listing 9-23a, the second DOWHILE-ENDDO group clears the normal CRT 
screen size of 23 lines. This is accomplished by first setting X to the value zero, 
followed by a DOWHILE group that checks the condition X,LSS,23 which iterates 
until X reaches the value 23. The WRITE statement within the DOWHILE group 
produces only the carriage return line-feed on each iteration because the character 
sequence within the brackets is empty. Following the WRITE statement, X is incre- 
mented by one, acting as a line counter. When X reaches 23, the RET statement 
following the matching ENDDO receives control, and the program terminates by 
returning to the console processor. Note that the DB statement for X provides the 
initial value zero, so that the first DOWHILE executes at least one time. 

Listing 9-23 b shows a portion of the program of Listing 9-23 a, with partial macro 
trace enabled. This trace does not show the generated labels ENDDl and DTEST1 
because no machine code was generated on those lines. The + M assembly parameter 
would show the labels, however. The locations of these labels can be derived from 
the hex listing to the left; the JNC ENDDl produces the destination address 01FF 
corresponding to the RET statement, and the JMP DTEST1 produces the address 
01E2 corresponding to the LDA X instruction at the beginning of the DOWHILE 
group. 
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The last control structure presented in this section is the SELECT-ENDSEL group, 
which corresponds to the FORTRAN computed GO-TO, the ALGOL switch state- 
ment, and the PL/M case statement. The general form of the SELECT group is 

SELECT id 
statement-set-0 
SELNEXT 
statement-set- 1 
SELNEXT 

SELNEXT 

statement-set-n 

ENDSEL 

where id is a data label corresponding to an 8 -bit value in memory, and statement 
set through n denotes groups of statements separated by SELNEXT delimiters. 

The action of the SELECT-ENDSEL group is as follows: the variable given in the 
SELECT statement is taken as a case number assumed to be in the range through 
n. If the value is 0, statement-set-0 is executed and, upon completion of the group, 
control transfers to the statement following the ENDSEL. If the variable has the 
value 1, then statement-set- 1 executes. Similarly, if the variable produces a value i 
between and n, then statement-set-i receives control. There can be up to 255 
groups of statements within each SELECT-ENDSEL group, and any number of dis- 
tinct SELECT-ENDSEL groups. Nested SELECT-ENDSEL groups are not allowed. 
That is, a SELECT-ENDSEL group cannot occur within a statement-set that is enclosed 
in another SELECT-ENDSEL group. As a convenience, the variable following the 
SELECT can be omitted, in which case the current 8080 accumulator content selects 
the proper case. 

Listings 9-24a and 9-24b show the SELECT macro library that implements the 
SELECT-ENDSEL group. The general strategy is to count the cases as they occur, 
starting with the SELECT, delimited by NEXTSEL, and terminated by ENDSEL. As 
the cases occur, a case label is generated that takes the form CASEn@m where n 
counts the SELECT-ENDSEL groups, and m is the case number within group n. A 
jump instruction is generated at the end of each case to the label ENDSn that marks 
the end of the SELECT group number n. Upon encountering the end of the group, a 
select-vector is generated that contains the address of each case within the group, 
headed by the label SELVn, where n is again the group number. Machine code is 
thus generated at the SELECT entry, which indexes into the select vector, based upon 
the SELECT variable, to obtain the proper case address. The first statement within 
the case receives control based upon the value obtained from this vector. 
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The general form of the machine code generated for the first SELECT group within 
a program (group n = 0) is: 

LDA id 

LXI SELVO 

(index HL by id, and 

load the address to HL) 

PCHL 
CASE0@0: 

statement-set-0 

JMP ENDSO 
CASE0@1: 

statement-set- 1 

JMP ENDSO 

CASE@n: 

statement-set-n 

JMP ENDSO 
SELVO: 

DW CASE0@0 

DW CASE0@1 

DW CASE0@n 
ENDSO: 

Listing 9-24a contains the label generators GENS LXI (generate SELECT LXI), 
GENCASE (generate case labels), GENELT (generate select vector element), and 
GENSLAB (generate SELECT label). Listing 9-24b contains the macro definitions for 
SELNEXT (select next case), SELECT, and ENDSEL. 

In Listing 9-24b, the SELECT macro begins by zeroing CCNT which counts SELECT- 
ENDSEL groups and then redefines itself, similar to the WHEN and DOWHILE 
macros. The redefined SELECT macro then generates the select vector indexing oper- 
ation by loading the indexing variable, if necessary, and then fetches the specific case 
address. No machine code is generated to check that the indexing variable is within 
the proper range. The PCHL at the end of this code sequence performs the branch 
to the selected case. 
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At the end of the redefined select macro, SELNEXT is invoked automatically, to 
delimit the first case in the SELECT group (otherwise SELECT would have to be 
followed immediately by SELNEXT in the user program to generate the proper 
labels). SELECT also zeros the ECNT variable, which counts the cases until ENDSEL 
is encountered. 



macro library for "select" construct 

label Generators 
Genslxi macro num 
55 load hi with address of case list 

lxi h »sely&num 

endM 
5 

Gencase macro num>elt 
5! Generate Jmp to end of cases 

if elt st 

Jmp ends&num 55past addr list 

endif 
5! Generate label for this case 
case&num&i&elt: 

endm 
5 

Genelt macro num»elt 
55 Generate one element of case list 

dw case&num&S&elt 

endm 
5 

Genslab macro num»elts 
5 5 Gene rate case list 
selu&num: 
ecnt set Jicount elements 

rept elts iiGenerate dw's 

Genelt num>'£ecnt 
ecnt set ecnt+1 

endm 5 iend of dw 's 

55 Generate end of case list label 
ends&num: 

endm 



Listing 9-24a. Macro Library for SELECT Statement 
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selnext macro 

55 Generate the next case 

3 e n c a s e Xccntt^ecnt 
ii increment the case element count 
ecnt set ecnt+1 

endm 



select 



cent 
select 



ecnt 



mac ro 

Sene rat 

set 

mac ro 

select 

if 

Ida 

endif 

Senslxi 

mo v 

my i 

dad 

dad 

mou 

inx 

mo v 

xchs 

pchl 

set 

endm 

i n v o k e 

select 

selnext 

endm 



gar 
e case selection code 

5 5 count "selects" 

y 5 5 redefinition of select 

on v or accumulator contents 

not nul u 

v !51oad select variable 

Xccnt 5 5Senerate the lxi h > s e 1 v * 

e »a 5icreate double precision 

d 1 5 5 u in d t e pair 

d 5 isinSle prec index 

d ? idoub le prec index 

e »m 5ilow order branch addr 

h 5!to h i 3 h order byte 

d >m Jihish order branch index 

5 5 ready branch address in hi 
5 5 Son e to the proper case 
5 ielement counter reset 

redefined select the first time 
uar 

^automatically select case < 



endsel macro 

5 5 end of select* Generate case list 

Sen case X cent* X ecnt iilast case 
Senslab 'Iccnt »%ecnt iicase list 

55 increment "select" count 

cent set ccnt+1 
endm 



Listing 9-24b. Library for SELECT Statement 

You use SELNEXT, shown at the top of Listing 9 -24b, to delimit cases. The 
GENCASE utility macro is invoked which, in turn, generates a JMP instruction for 
the previous group, if this is not group zero, and then produces the appropriate case 
entry label. SELNEXT also increments the select element counter ECNT to account 
for yet another case. 
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Upon encountering the ENDSEL, the last macro in Listing 9-24b, GENCASE is 
again called to generate the JMP instruction for the last case. GENSLAB then pro- 
duces the select vector by first generating the SELVn label, followed by a list of 
ECNT DW statements that have the case label addresses as operands. 

Listing 9-25a gives an example of a simple program that uses two SELECT groups. 
The first SELECT group executes one of five different MVI instructions based on the 
value of X. The second SELECT group assumes that the 8080 accumulator contains 
the selector index and executes one of three different MVI instructions. The program 
of Listing 9-25 a illustrates generated control structures, and does not produce any 
useful values as output. The sorted Symbol Table shown at the end of the listing 
gives the generated label addresses for the individual cases. 

Listing 9 -25 b shows a segment of the previous program with generated macro 
lines. Note the case selection code following SELECT X at the end of the listing. 

Listing 9-25 c gives a more complete trace of the SELECT-ENDSEL group, showing 
the actions of the macros as they expand for the second SELECT-ENDSEL group of 
Listing 9-25 a. The listing has been edited to remove the case selection code, which is 
listed in Listing 9-25b, and the code generated for case number 2. Cross-reference 
Listing 9-25 c with the SELECT macro library given in Listings 9-24a and 9-24b if 
you are confused about the actions of these macros. 
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MACLIB 


SELECT 


0000 




SELECT 


X 


0010 


3E00 


MVI 


A»0 


0012 




SELNEXT 




0015 


3E01 


MVI 


A»l 


0017 




SELNEXT 




001A 


3E02 


MVI 


A»2 


001C 




SELNEXT 




001F 


3E03 


MVI 


A»3 


0021 




SELNEXT 




0024 


3E04 


MVI 


A>4 


0026 




ENDSEL 




0033 


i 


SELECT 




0040 


0600 


MVI 


B»0 


0042 




SELNEXT 




0045 


0601 


MVI 


Bil 


0047 




SELNEXT 




004A 


0602 


MVI 


B»2 


004C 




ENDSEL 





0055 



DS 



0010 CASEOiO 
0029 CASEOiS 
0033 ENDSO 



0015 CASEOil 
0040 CASEliO 
0055 ENDS1 



001 A CASE0@2 
0045 CASElil 
0029 SELVO 



00 IF CASE0B3 
004A CASEli2 
004F SELV1 



0024 CASEO 4 
004F CASE1 3 
0055 X 



Listing 9-25a. Sample Program Using SELECT with — M +S Options 
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MACLIB 


SELECT 




SELECT 


X 


0000+3A5500 


LDA 


X 


0003+212900 


LXI 


HtSELMO 


0006+5F 


MOV 


E.A 


0007+1600 


MMI 


D»0 


0009+19 


DAD 


D 


000A+19 


DAD 


D 


000B+5E 


MOM 


EiM 


000C+23 


INK 


H 


000D+5G 


MOM 


D»M 


000E+EB 


XCHG 




000F+E9 


PCHL 




0010 3E00 


MMI 


AtO 




SELNEXT 


0012+C33300 


JMP 


ENDSO 


0015 3E01 


MMI 


Ail 




SELNEXT 


0017+C33300 


JMP 


ENDSO 


001A 3E02 


MMI 


A»2 




SELNEXT 


001C+C33300 


JMP 


ENDSO 


001F 3E03 


MMI 


A. 3 




SELNEXT 


0021+C33300 


JMP 


ENDSO 


0024 3E04 


MMI 
ENDSEL 


A. 4 


002G+C33300 


JMP 


ENDSO 


0029+1000 


DM 


CASEO@0 


002B+1500 


DW 


CASEOil 


002D+1A00 


DW 


CASE0@2 


002F+1F00 


DW 


CASE0B3 


0031+2400 


DM 


CASE0i4 




Listing 9-25b. Segment of 



Segment of Listing 9-25a with Mnemonics 
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SELECT 


+ 


IF NOT NUL 


+ 


LDA 


+ 


ENDIF 


+ 


GENSLXI ZCCNT 


:+2UF00 


LXI H.SELV1 


+ 


ENDM 



indexing code similar to Fig 50b) 



0000+* 


ECNT 


SET 





+ 




GENCASE 


XCCNT»ZECNT 


+ 




IF 


GT 


+ 




JMP 


ENDS1 


+ 




ENDIF 




+ 


CASEliO: 




+ 




ENDM 




000 1+* 


ECNT 


SET 


ECNT+1 


+ 




ENDM 




+ 




ENDM 




0040 0600 




MMI 
SELNEXT 


B.O 


+ 




GENCASE 


ZCCNT »ZECNT 


+ 




IF 


1 GT 


0042+C35500 




JMP 


ENDS1 


+ 




ENDIF 




+ 


CASE101: 




+ 




ENDM 




0002+* 


ECNT 


SET 


ECNT+1 


+ 




ENDM 





(remaining cases are similar) 



0000+* 



004F+4000 

+ 
0001+# 





ENDSEL 






GENSLAB 


ZCCNT. ZECNT 


SELV1: 






ECNT 


SET 







REPT 


3 




GENELT 


1 .ZECNT 


ECNT 


SET 
ENDM 


ECNT+1 




GENELT 


1 .ZECNT 




DW 


CASEliO 




ENDM 




ECNT 


SET 


ECNT+1 




GENELT 


1 .ZECNT 



Listing 9-25c. Segment of Listing 9-25a with +M Option 
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0051+4500 




DW 


CASEldl 


+ 




ENDM 




0002+* 


ECNT 


SET 


ECNT+1 


+ 




GENELT 1 »%ECNT 


0053+4A00 




DW 


CASE1H2 


+ 




ENDM 




0003+# 


ECNT 


SET 


ECNT+1 


+ 




ENDM 




+ 


ENDS1: 






+ 




ENDM 




0002+* 


CCNT 


SET 


CCNT+1 


+ 




ENDM 


Listing 9-25c. 



(continued) 



It is now possible to show a complete program that uses the WHEN, DO WHILE, 
and SELECT groups. Listing 9-26 shows a program similar in function to a more 
complicated program that interacts with the console in executing single-character 
input commands. The two CP/M programs ED and DDT both take this general form. 
(See the CP/M documentation for details.) A single letter selects a single action that 
might correspond to an edit request in the ED program or a debug request in DDT. 
Upon completion of each command, control returns to the main loop to accept 
another single-letter command. 

The program given in Listing 9-26 begins by loading the macro definitions for the 
SIMPIO, NCOMPARE, WHEN, DOWHILE, and SELECT operations. Several mes- 
sages are then sent to the console device, followed by a single DOWHILE-ENDDO 
group that encompasses nearly the entire program. The DOWHILE group is con- 
trolled by the X,NEW,%'D' test and thus continues to loop while the X character is 
not the letter D. On each iteration of the DOWHILE group, a single letter is read 
from the console and converted to upper-case, if necessary. To ensure that the letter 
is in the proper range of values, two WHEN groups follow that convert illegal values 
to the letter E, which subsequently produces an error response. 
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Following the WHEN tests in Listing 9-26, the character must be in the range A 
through E. Before indexing into the SELECT group, this value is normalized to the 
absolute value through 4, corresponding to each of the possible values. The SELECT 
statement uses the value in the accumulator to select one of the five cases, producing 
the appropriate response to the letters A through D, or an error response for the last 
case. Upon completion of the SELECT group, control returns to the DOWHILE 
where the last character typed is tested against the letter D. If X is not equal to the 
letter D, the iteration continues. Otherwise, the DOWHILE completes and control 
returns to the console processor. 

The control structures presented in this section are representative of the forms that 
can be implemented. Additional facilities, such as the controlled iteration found in 
FORTRAN DO loops or ALGOL FOR loops can be implemented using essentially 
the same techniques used for the WHEN and DOWHILE. Further, subroutine 
parameters can also be defined with macro libraries. It is relatively easy to include 
control substructures for the stack machine given in the previous section, allowing 
machine independent programming of control structures and arithmetic operations. 



178 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.3 Program Control Structures 



0100 



BEGINNING OF TPA 
SIMPLE READ/WRITE 
COMPARISON OPS 
"WHEN" CONSTRUCT 
"DOWHILE" CONSTRUCT 
"SELECT" CONSTRUCT 



USING THE CCP'S STACK. READ INPUT 
CHARACTERS. UNTIL A Z IS TYPED 



ORG 


100H 


MACLIB 


SIMPIO 


MACLIB 


NCOMPARE 


MACLIB 


WHEN 


MACLIB 


DOWHILE 


MACLIB 


SELECT 



0100 




WRITE <SAMPLE CONTROL STRUCTURES) 


0127 




WRITE <TYPED SINGLE CHARACTERS FROM 


0150 




WRITE <A TO D. I""'LL STOP ON D> 


0174 


i 


DOWHILE XtNEOfI'D' 


017C 




WRITE <TYPE A CHARACTER: > 


019C 




READ X 


01A4 




WHEN X.GEO.I'A' 


01AC 


3ABF02E65F 


LDA X! AN I 05FH! STA X 5C0NU CASE 


01B4 




ENDW 


01B4 




WHEN X.LSS.X'A' 


01BC 


3E4532BF02 


MVI A.'E' ! STA X 5 SET TO ERROR 


01C1 




ENDW 


01C1 




WHEN X.GTR.Z'E' 


01CC 


3E4532BF02 


MUI A.'E' ! STA X 5SET TO ERROR 


01D1 




ENDW 


01D1 


3ABF02DG41 


LDA X! SUI 'A' 5N0RMALIZE TO 0-4 


01D6 




SELECT 5BASED ON X IN ACCUM 


01E3 




WRITE <YOU SELECTED CASE A> 


0204 




SELNEXT 


0207 




WRITE (YOU SELECTED CASE B> 


0228 




SELNEXT 


022B 




WRITE (YOU SELECTED CASE C> 


024C 




SELNEXT 


024F 




WRITE <YOU SELECTED CASE D> 


0270 




WRITE <S0 I "M GOING BACK-'! > 


0290 




SELNEXT 


0293 




WRITE -(BAD CHARACTER) 


02AE 




ENDSEL 


02BB 




ENDDO 


02BE 


C9 

5 


RET 5BACK TO CCP 
DATA AREA 


02BF 


00 X: 


DB !X=00 INITIALLY 



Listing 9-26. Program Using WHEN, DOWHILE, and SELECT 
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9.4 Operating System Interface 

In a general purpose computing environment, macros often provide systematic and 
simplified mechanisms for programmatic access to operating system functions. 
Throughout this manual, the examples have shown various low-level calls to the 
CP/M operating system that implement functions such as single-character input, sin- 
gle-character output, and full message output. In each case, the macros simplify the 
operations by performing the low-level register setups and calls that perform the 
function. 

This section introduces more comprehensive operating system interface macros and 
shows a sample macro library that allows simplified disk file operations for sequen- 
tial stream input/output operations. The principal macros of this library that allow 
file access are listed below: 

FILE set up a named file for subsequent disk operations. 

GET read a single character from specific data source. 

PUT send a character to a specific data destination. 

FINIS terminate file access for specific group of files. 

ERASE remove a specific disk file. 

DIRECT search for a specific file on the disk. 

RENAME rename a specific disk file. 

Before introducing the macro library that performs these functions, the operation of 
each macro is described, followed by a simple example. 

The FILE operation takes the form: 

FILE mode,fileid,diskname,filename,filetype,buffsize,buffadr 

where the individual parameters of the FILE macro describe a file to be accessed in 
the program. The parameter values for the FILE macro are: 

mode INFILE (input file) 

OUTFILE (output file) 

SETFILE (set up filename for ancillary functions) 
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fileid file identifier for internal reference throughout the program. 

diskname disk drive name (A, B,. . .) containing the file being accessed, or 

empty if the default drive is being used. 

filename the filename (up to eight characters) of the disk file being accessed; 

if "1" or "2" is specified, then the first or second default filename 
is used, respectively. 

filetype the filetype (up to three characters) of the file being accessed; if 

"1" or "2" has been specified for the filename parameter and an 
empty filetype is given, then the filetype is taken from the selected 
default filename; otherwise, the filetype is set to blanks. 

buff size the size in bytes of the buffer area used for this file; the value is 

rounded down to an integral multiple of the disk sector size; if 
the rounding produces a result that is too small, or if the param- 
eter is empty, then only one sector is buffered. 

buffaddr the address of the buffer area to use during accesses to this file; 

if empty, then the buffer address is assigned automatically. 

For example, the FILE statement 

FILE INFILE »ZOT »A »NAMES*DAT 

sets up the file NAMES.DAT on disk drive A for subsequent access. Internal to the 
program, this file is referenced by the name ZOT. Further, the buffer address is 
assigned automatically, and the buffer size is set to one sector (usually 128 bytes). 
Larger buffers are useful in minimizing rotational delay on the disk due to missed 
sectors during the file operations. If the NAMES.DAT file does not exist, an error 
message is sent to the console, and the program aborts. For example, an output file 
can be created using the statement: 



FILE 



OUTFILE»ZAP »B ^ADDRESS »DAT »1000 



which creates the file ADDRESS.DAT on drive B for subsequent output, referenced 
internally by the name ZAP. In this case, the buffer size is set to 1000 bytes (rounded 
down to 7 * 128 = 896 bytes), and the base address of the buffer is set r"<-nmati- 
cally. The sample programs show alternative FILE options. 
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The GET macro invocation takes the form: 

GET device 

where device specifies a simple peripheral or a disk file defined by a previously 
executed FILE statement. The GET statement reads one byte of data into the 8080 
accumulator from the specified device. The possible device names are: 

KEY console keyboard input 

RDR reader device 

fileid previously defined file identifier given in a FILE statement 

The following GET invocations perform the functions shown to the right below. 

GET KEY read one keyboard character. 

GET RDR read one reader character. (See the CP/M documentation for 

READER entry point definition.) 

GET ZOT read one character from the file given by the internal name ZOT. 

(The NAMES.DAT file if the above FILE statement had been 
executed.) 

The end-of-data can be detected in two ways: if the file contains character data, the 
end-of-file is detected by comparing the individual characters with the standard 
CP/M end-of-file mark, which is a CTRL-Z (hexadecimal 1AH). The GET function 
also returns with the 8080 zero flag set to true if a real end-of-file is encountered, so 
that pure binary files can be read to the end-of-data. 

The PUT macro performs the opposite function from the GET macro. The PUT 
invocation takes the form: 

PUT device 
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where device specifies a simple output peripheral or a disk file defined previously 
using the FILE macro. The possible device names are 

CON console display device 

PUN system punch device 

LST system listing device 

fileid previously defined output file identifier 

These PUT invocations perform the following functions: 

PUT CON write the accumulator character to the console. 

PUT PUN write the accumulator character to the punch. 

PUT LST write the accumulator character to the list device. 

PUT ZAP write the accumulator character to the file with the internal name 

ZAP. (The ADDRESS.DAT file in the preceding example.) 

Note that the character in the accumulator is preserved during the invocation, so 
that it can be involved in further tests or macro invocations following the PUT 
statement. 

The FINIS statement closes a file or set of files upon completion of file access. In 
the case of an output file, the internal buffers are written to disk, and the filename is 
permanently recorded on the disk for future access. The form of the FINIS invocation 
takes the form: 

FINIS filelist 

where filelist is a single internal name that appeared previously in a file statement or 
a list of such filenames, enclosed within angle brackets and separated by commas. 
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Although it is not necessary to close input files with the FINIS statement, it is good 
practice, because the file close operation might be required on future versions of the 
macro library. An example of the FINIS statement is: 

FINIS ZAP 

write all buffers for the ZAP file, and record the file in the disk directory; in the 
above example, the ADDRESS.DAT file is closed. 

The ERASE macro allows programmatic removal of a disk file given by the speci- 
fied file identifier defined in a previous FILE statement. If the file identifier is not used 
in a GET or PUT statement, then the FILE statement can have the mode SETFILE. 
This mode requires less program space than an INFILE or OUTFILE parameter. 
Examples of the ERASE statement are given later in this section. In the example 

ERASE ZOT 

however, the file NAMES.DAT is removed from the disk, given the previous FILE 
statement that defines ZOT. 

The DIRECT macro searches for a specific file on the disk. Similar to the ERASE 
macro, the file identifier must be previously given in a FILE statement using one of 
the three possible file modes. The DIRECT invocation sets the 8080 zero flag to false 
if the file is present on the disk. In both the ERASE and DIRECT macros, the file 
identifiers can reference filenames and types with embedded ? characters, similar to 
the normal CP/M DIR command, where the question mark matches any character in 
the filenames being scanned. The macro invocation 

DIRECT ZAP 

for example, returns with the zero flag cleared if the file ADDRESS.DAT is present, 
and with the zero flag set if the file is not present, given the original FILE statement 
involving the ZAP file identifier. 

The RENAME macro takes the form: 

RENAME newfile,oldfile 

where newfile and oldfile are file identifiers that have appeared in previous FILE 
statements. The RENAME macro changes the filename given by oldfile to the file- 
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name given to newf ile. The file identifiers newf ile and oldf ile must appear in previously 
executed FILE statements, but can have a mode of SETFILE if they are not used in GET 
or PUT macros. If the drive names for oldfile and newfile differ, then the drive name of 
newfile is assumed. The sequence of macro invocations 



FINIS 


ZAP 




5CL0SE ZAP 


ERASE 


ZOT 




i REMOVE ZOT 


RENAME 


ZOT : 


► ZAP 


5CHANGE NAMES 



for example, first closes the ADDRESS.DAT file on drive B, then erases the 
NAMES.DAT file on drive A. The RENAME macro then changes the ADDRESS.DAT 
file to the name NAMES.DAT file on drive A. 

Listing 9-27 shows the use of the FILE, GET, PUT, and FINIS macros in a working 
program. This program reads an input file, specified at the Console Command Pro- 
cessor level as the first filename, and translates each lower-case alphabetic character 
to upper-case. The output is sent to the file given as the second parameter at the 
command level. For a program assembled, loaded, and stored as CASE.COM on the 
disk, a typical execution would be 

CASE LOWER*DAT UPPER.DAT 

This causes the CASE.COM file to load and execute in the Transient Program Area. 
Before execution, the Console Command Processor passes LOWER.DAT as the first 
default filename, and UPPER.DAT as the second filename. (See the CP/M documen- 
tation for exact details.) 

In Listing 9-27, the CASE program begins by initializing the stack pointer to a 
local stack area in preparation for subsequent subroutine calls that occur within the 
various macros in the SEQIO macro library. The first default file specification is then 
taken as the SOURCE file, as defined in the first FILE macro. The second FILE 
statement assigns the second default file specification as an output file with the inter- 
nal name DEST. In both cases, the FILE statements open the respective files and 
initialize the buffer areas, consisting of 2000 bytes rounded down to a multiple of 
the sector size. 

Note that if the UPPER.DAT file already exists, the second file statement removes 
the existing file and creates a new UPPER.DAT file before continuing. In either case, 
the appropriate error messages appear at the console if the files cannot be accessed 
or created in the FILE statements. 
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0100 



ORG 100H 

COPY FILE 1 TO FILE 2. CONVERT 
TO UPPER CASE DURING THE COPY 
AND ECHO TRANSACTION TO CONSOLE 
MACLIB SEOIO SEQUENTIAL I/O LIB 



0000 


= 


BOOT 


EQU 


OOOOH 


5SYSTEM REBOOT 


005F 


= 


UCASE 


EQU 


5FH 


5UPPER CASE BITS 


0100 


317003 


i 


LXI 


SP .STACK 










DEFINE 


SOURCE FILE: 










INFILE 


= INPUT FILE 










SOURCE 


= INTERNAL NAME 










(NUL) 


= DEFAULT DISK 










1 


= FIRST DEFAULT NAME 










(NUL) 


= FIRST DEFAULT TYPE 










2000 


= BUFFER SIZE 



0103 



FILE 



INFILE. SOURCE. .1 . .2000 



DEFINE DESTINATION FILE: 

OUTFILE = OUTPUT FILE 

DEST = INTERNAL NAME 

(NUL) = DEFAULT DISK 

2 = SECOND DEFAULT NAME 

(NUL) = SECOND DEFAULT TYPE 

2000 = BUFFER SIZE 



01EC 



FILE 



OUTFILE. DEST ..2. .2000 



5 READ SOURCE FILE. TRANSLATE. WRITE DEST 

02EA CYCLE: GET SOURCE 

02ED FE1A CPI EOF 5END OF FILE? 

02EF CA0C03 JZ ENDCOPY 5SKIP TO END IF SO 

5 

; NOT END OF FILE. CONUERT TO UPPER CASE 

02F2 FEB1 CPI 'a' iBELOW LOWER CASE "A"? 

02F4 DAFE02 JC NOCONV 5SKIP IF SO 

02F7 FE7B CPI 'z'+l iBELOW LOWER CASE "Z"? 

02F9 D2FE02 JNC NOCONM 5SKIP IF ABOVE 

5 MASK OUT LOWER CASE ALPHA BITS 

02FC EB5F ANI UCASE 

02FE NOCONM: PUT CON 5WRITE TO CONSOLE 

0306 PUT DEST ?AND TO DESTINATION FILE 

0309 C3EA02 JMP CYCLE 5F0R ANOTHER CHARACTER 



Listing 9-27. Lower- to Upper-case Conversion Program 



186 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.4 Operating System Interface 





ENDCOPY: 








030C 


FINIS 


DEST 


;end of output 




034D C30000 


JMP 


BOOT 


5BACK TO CCP 




0350 


DS 


32 


ilG LEVEL STACK 






STACK: 










BUFFERS: 








1270 = 


MEMSIZE 


EQU 


BUFFERS+0NXTB 


iPROGRAM SIZE 


0370 


END 









Listing 9-27. (continued) 



The CASE program main loop is shown in Listing 9-27 between the CYCLE and 
ENDCOPY labels. Each successive character is read from the SOURCE file (in this 
case, LOWER.DAT) and tested to see if the character is in the range of a lower-case 
a to lower-case z. If in this range, the character is changed to upper-case. At the 
NOCONV label, the (possibly translated) character in the accumulator is sent to the 
console device using the PUT CON macro and then sent to the DEST file (in this 
case, UPPER.DAT). Looping continues back to the CYCLE label where another 
character is read and translated. 

Because the data file is assumed to consist of a stream of ASCII characters, the 
end-of-file is detected when a CTRL-Z is encountered. When this character is found, 
control transfers to the label ENDCOPY where the DEST file is closed using the 
FINIS macro. An error in writing or closing the DEST file produces an error message 
at the console, and the program aborts immediately. Upon completion of the pro- 
gram, control returns to the console processor through a system reboot (JMP BOOT). 

The SEQIO library macros assume that all file buffers are located at the end of the 
user's program, as shown in Listing 9-27. In particular, the label BUFFERS must 
appear as the last label in the user's program, and becomes the base of the buffers 
allocated automatically in the FILE statements. The actual memory requirements for 
the program can be determined using an EQU as shown in Listing 9-27, with a 
statement of the form: 



MEMSIZE 



EQU 



BUFFERS+SNXTB 



that produces the equated value 1270H at the left of the listing. In this case, the 
program does not use the memory area beyond 1270H. 
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The macro library for SEQIO is shown in Listing 9-28. This listing is the most 
comprehensive macro library shown in this manual, containing an instance of nearly 
every macro facility available in MAC. The following discussion of SEQIO outlines 
the general functions of each macro, but it is left to you to investigate the exact { 

operation of the library. ^ 

The SEQIO library begins with generally useful equates and utility macros. The 
label FILERR at the beginning becomes the destination of transfers upon encounter- 
ing a file operation error. Because this is a SET statement, it can be changed in the 
user's program to trap error conditions rather than rebooting. The use of FILERR is 
apparent throughout the macro library. 



sequential file i/o library 



f i le rr 


set 


0000 h 


5 reboot after error 




@bdos 


eiu 


0005 h 


5 b d o s entry paint 




@tf cb 


eiu 


005 c h 


idefault file control bl 


ock 


itbuf 

5 

5 


e<=iu 
bdos 


0080 h 
f u'n c t i o n s 


i d e f a u 1 1 buffer address 




8W5 3 


equ 


9 


i s e n d message 




@opn 


equ 


15 


i f i 1 e open 




icls 


equ 


IB 


if i 1 e close 




idi r 


esu 


17 


idirectorv search 




@del 


equ 


19 


ifile delete 




@f rd 


equ 


20 


5file read operation 




ifwr 


equ 


21 


? f i 1 e write operation 




Sftiak 


equ 


r ? r ? 


5 f i 1 e make 




iren 


equ 


23 


ifile rename 




@dma 


equ 


26 


iset dm a address 




isect 


equ 


128 


isector size 




eof 


equ 


lah 


iend of file 




c r 


equ 


Odh 


icarriatfe return 




If 


equ 


Oah 


iline feed 




tab 


equ 


09h 


ihorizontal tab 




1 

@kev 


equ 


1 


5 k e y b o a r d 




Scon 


equ 


2 


iconsole display 




8rd r 


equ 


3 


i reade r 




@pun 


equ 


4 


ipunch 




Blst 


equ 


5 


ilist device 
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5 Keywords for "file" macro 

infile eiu 1 iinput file 

outfile e <=i u 2 ioutputfile 

setfile e qu 3 Jsetup name only 

5 

! the following macros define simple sequential 

5 file operations: 

! 

f i 1 lnam mac ro f c »c 

55 fill the file name/type Siuen by fc for c characters 

Sent set c ! imax length 

irpc ?fc»fc iifill each character 
5! may be end of count or nul name 





if 


icnt=0 


or nul ?f c 




exi tm 








end if 








db 


'&?FC 


iifill one more 


@cnt 


set 


@cnt-l 


!i decrement max length 




endm 




;?of irpc ?fc 


1 1 

5 5 


pad remainder 






rept 


Sent 


5 ! @ c n t is remainder 




db 


' ' 


iipad one more blank 




end m 




i 5of rept 




endm 






f Hide 


f 


mac ro 


feb f ?f 1 i?ln 



J! fill the file naMe from the default feb 
5 i for length ?ln (9 or 12) 
local psub 

Jmp ps ub 5 5 Jump past the subroutine 
@ d e f : i 5 1 h i s subroutine fills from the t f c b ( + 1 B ) 

5i3et next character to a 
? isto re to feb area 



iiicount length down to 



mou 


a »m 


stax 


d 


inx 


h 


inx 


d 


dc r 


c 


Jnz 


@def 


ret 
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55 end of fill subroutine 

psub : 

filldef macro ?fob»?f>?l 

5 ieither @tf cb or @tfcb+iG 

5 ilenath = 9 »12 



lxi 




h »@tf cb+?f 


lxi 




d»?fcb 


mv i 




Of?l 


call 




@def 


endm 






f i 1 Id 


>f 


fcb»?f 1 »?in 


endm 







f i 1 lnxt mac ro 

55 initialize buffer and device numbers 

5 5 n e x t buffer location 
55next device number 



inxtb set 





inxtd set 


ilst+1 


f illnxt 


mac ro 


en dm 




endm 




f i 1 If cb 


mac ro 



f id >dn ifn »f t »bs >ba 
fill the file control block with disk name 
fid is an internal name for the file* 
dn is the drive name (a»b..)> or blank 
fn is the file name* or blank 
ft is the file type 
bs is the buffer size 
ba is the buffer address 
local pfcb 

set up the file control block for the file 

look for file name = 1 or 2 

8c set 1 5 5 a s s u m e true to beSin with 

irpc ?c>fn 551ook through characters of name 

if not ( '&?C = '1 ' or '&?C = '2') 

@c set liclear if not 1 or 2 

endm 
55 ic is true if fn = 1 or 2 at this point 

if @c 5 5then fn = 1 or 2 

5! fill from default area 

if nul ft 55type specified? 

@c set 12 5 5both name and type 

else 
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@c set 9 5 iname only 

endif 

filldef f cb&f id >(fn-l )*16 >@c 5ito select the fcb 

Jmp pfcb 55past fcb definition 

ds @c jispace for d rive/f i lename/type 

fillnain ft»12-@c iiseries of db's 

else 

Jmp pfcb 55past initialized fcb 

if nul dn 

db !5use default drive if name is zero 

else 

db '8eDN'-'A' + l • iJuse specified drive 

endif 

fillnam f n »8 55fill file name 
5! now Generate the file type with padded blanks 

fillnam ft»3 iiand three character type 

endif 
fcb&fid equ $-12 JibesfinninS of the fcb 

db itextent field 00 for setfile 
!! now define the 3 byte field* and disk map 

ds 20 i ix >x >rc »dmO. . .dml5 >c r fields 
5 i 

if fid&typ<=2 iiin/outfile 
!i Generate constants for inf i le/outf ile 

fillnxt 5!@nxtb=0 on first call 

if bs+0<@sect 
5 i bs not supplied* or too small 
@bs set isect 55default to one sector 

else 
!! compute euen buffer address 
@bs set (bs/isect )*@sect 

endif 
5 I 
!i now define buffer base address 

if nul ba 
i5 use next address after dnxtb 
fid&buf set buf f e rs+@nxtb 
5 i count past this buffer 
@nxtb set @nxtb+ bs 

else 
fid&buf set ba 

endif 
5i fid&buf is buffer address 
f id&adr: 

dw fid&buf 
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fid&siz eiu ibs 551iteral size 
f id&len: 

dw @bs 55buffersize 
f id&pt r: 

ds 2 55set in inf ile/outf ile 
55 set device number 
@&fid set @nxtd 55next device 
Snxtd set @nxtd+l 

endif 55of fid&typ<=2 test 
pfcb: endm 
5 
file Macro md »f id »dn >f n >t t »bs »ba 

create file usinS mode md: 

inf i le = 1 input file 
outfile = 2 output file 
setfile = 3 setup fcb 

(see fillfcb for remaining parameters) 

local PSUb »MS 3 >PM53 

local pnd »eod teob tpnc 
5 5 construct the file control block 
5 5 

fid&t/p equ md 55set mode for later ref's 

fillfcb fid >dn »fn >f t >bs »ba 

if md = 3 5 5 s e t u p fcb only* so exit 

ex i tm 

endif 
55 file control block and related parameters 
55 are created inline* now create io function 

Jmp psub 55past inline subroutine 

if md=l 55inputfile 
Setkf id: 

else 
put&f id: 

push psw iisaue output character 

endif 

lhld fid&len 551oad current buffer length 

xchs 5 5de is length 

lhld fid&ptr 551oad next to Set/put to hi 

mou a»l 55compute cur-len 

sub e 

mov ath 

sbb d 55carry if next<len3th 

Jc pnc SScarry if len Str current 
55 end of buffen fill/empty buffers 

lxi h»0 

shld fid&ptr 55clear next to Set/put 
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prid : 



proce 

xchs 

lhld 

de is 

mov 

sub 

mov 

sbb 

Jnc 

carry 

lhld 

dad 

xchs 

mui 

call 

lxi 

if 

my i 

else 

mui 

endif 

call 

o ra 

Jnz 

not e 

lxi 

lhld 

dad 

shld 

Jmp 



ss next disk sector: 

i if id&ptr to de 
fidMen iido not exceed lensth 
next to fill/empty* hi is max len 
a »e 5 icompute next-1 en 

5 5 to Set carry if more 



1 5 
a >d 

h ; 
eob 
Sen 'ed » hen 
fid&adr i 



c »@dma i 
ibdos i 
d tfcb&f id 
m d = 1 5 
c »@f rd i 



»to fill 

ce more to fill/empty 

ibase of buffers 

ihl is next buffer addr 

!set dma address 
idma address is set 

5 if cb address to de 
iread buffer function 
i f i 1 e read f unct ion 



c»@fwr iifile write function 

@bdos iird/wr to/from dma address 

a iicheck return code 

eod iiend of file/ d is K ? 
nd of file/disKf increment lenSth 

d >@sect iisector size 

f id&pt r i inext to fill 
d 

fid&ptr iiback to memory 

pnd iiprocess another sector 



eod 



end of file/disk encountered 



if 


md = l 


lhld 


f id&ptr 


shld 


f idklen 


else 




fatal 


error* en 


local 


emss 


my i 


c timss 


lxi 


d »emsS 


call 


ibdos 


POP 


PSW 


JMP 


f i le r r 



i input file 
ilensth of buffer 
5 reset lenSth 



iiwrite the error 

i ie rro r to consol e 
iiremove stacked character 
5 5 usually reboots 
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emsSi 



db 
db 
db 
endif 



cr » 1 f 

'disk full 



&FID 



eob ; 



end of buffer* reset dma and pointer 

lxi dtitbuf 

frwi c »@dma 

call @bdos 

lxi h >0 

shld fid&ptr iinext to Set 



process the next 
xch 3 



lh Id 

dad 
xchs 
if 

1 h Id 
hiou 
o ra 
my i 
rz 



f id&adr 
d 

wd = l 

f id&len 

a»l 

h 

a >eof 

d 



ldax 
else 
store next charac 



POP 

stax 

endif 

lhld 

inx 

shld 



PSW 

d 



cha racte r 

iindex to * e t / p u t in de 
ibase of buffer 
iaddress of char in hi 
5 a d dress of char in de 
linput processing differs 
5for eof check 
5 0000? 

Send of file? 
izero flaS if so 
inext char in accum 

ter from accumulator 
! r e c a 1 1 saved char 
icharacter in buffer 



fid&Ptr 5iindex to Set/put 

h 

f id&Pt r 
return with non zi 
ret 



Jpointer updated 
:ero fla3 if sfet 



Listing 9-28. (continued) 



194 



At 



PRESEt 



HERE 



>ROPRlETARY TO DIGITAL RESEARCH 



Programmer's Utilities Guide 



9.4 Operating System Interface 



psub ! 



pmsS: 



5 ipast 

x ra 

sta 

sta 

lxi 

shld 

if 

shld 

MUi 

else 

lxi 

shld 

mui 

lxi 

call 

mvi 

endif 

now op 

lxi 

call 

in r 

Jnz 

wui 

lxi 

call 

Jmp 

db 

if 

db 

else 

db 

endif 

db 

endht 



inline subroutine 
a 5 5ze ro to ace 

f cb&f id + 12 i iclear extent 
f cb&f id+32 5 iclear cur rec 
htfid&siz 5 5 b u f f e r size 
fid&len 55set buff len 
md = l 5 5 input file 
fid&ptr 55cause immediate read 
c »iopn 5iopen file function 

! ioutput file 
h»0 !5set next to fill 
fid&ptr 55pointer initialized 
c »idel 

d »f cb8tf id i idelete file 
ibdos 55to clear existing file 
c >@maK 5!create a new file 

en (if input) i or maKe (if output) 
d .fcb&f id 

ibdos 5 Jopen/waKe ok? 
a 55255 becomes 00 



pmsS 
c »8msS 

d >MS3 

@bdos 
f i le rr 
cr »lf 
md = l 



Jprint message function 
5e rro r message 
Jprinted at console 
5to restart 

55input message 



'no &FID f ile ' 



'no dir space: &FID' 



'$' 



finis mac ro fid 

5! close the file(s) tfiven by fid 

irp ?f»<fid> 

55 skip all but output files 

if ?f&typ=2 

local eob? »peof >msd »pmsS 

55 write all partially filled buffers 
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eob?: iiare we at the end of a buffer? 

lhld ?f&Ptr 55next to fill 

fiiov a*l 5 ? on buffer boundary? 

ani (Ssect-1) and Of f h 

Jnz peof 5!put eof if not 00 

if @sect>255 

55 checK h i Sh order byte also 

mou a*h 

ani (@sect-i ) shr 8 

Jnz peof !5put eof if not 00 

endif 
5! arriue here if end of buffer* set lenSth 
55 and write one more byte to clear buffs 





shld 


?f&len 5 


5set to shorter length 


peof : 


Mui 


a »eof 5 


iwrite another eof 




push 


psw 5 


5save zero flaS 




call 


put&?f 






POP 


psw 5 


! recal 1 zero f las 




Jnz 


eob? 5 


!non zero if more 


! 5 


buffers 


have been 


written* close file 




mui 


c »8cls 






lxi 


d.fcb8=?f 


5 5 ready for cal 




call 


ibdos 






in r 


a ; 


5255 if err becomes 00 




Jnz 


pmsS 




! 5 


file cannot be cl 


osed 




mui 


c *8msS 






lxi 


d *ms* 






call 


ibdos 






Jmp 


pms3 5 


5e rro r message printed 


mss: 


db 


c r >lf 






db 


'cannot c 


lose &?F' 




db 


'$' 




pfiis s : 


endif 








endm 


5 5 of the 


i rp 




en dm 






e rase 


macro 


fid 




5 5 


delete 


the f i 1 e ( s 


) Siven by fid 




i rp 


?f »<fid> 






mvi 


c »@del 






lxi 


d»fcb8c?f 






call 


@bdos 






endm 


» i of the 


i rp 




endm 
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direct macro fid 

55 perform directory search for file 

5! sets zero flaS if not present 



@rens : 



renO: 



lxi 
mvi 
call 
in r 
endm 

rename macro 
rename 
local 
include 
Jmp 

5 5 renam 
55old f 
push 
lxi 
dad 
ldax 
mov 
inx 
inx 
dc r 
Jnz 

5 5 old nam 

POP 

mui 

call 

ret 

psub: 

rename macro 
lxi 
lxi 
call 
endm 
rename 
endm 



d»fcb8,fid 
c »@di r 
@bdos 



500 if not present 



new >old 
file Siuen by "old" to "new" 

psub » renO 

the rename subroutine once 

psub 
e subroutine* hi is address of 
cb» de is address of new fcb 

h 5 isave f o r rename 

b»16 55b=00»c=16 

b ; ; h 1 = old fcb + 16 

d 5 5new f cb name 

m >a 5 5 to old f cb + lG 

d 5 5next new char 

h 5 inext fcb char 

c 5 icount down f rom IB 

renO 
e in first halft new in second half 

d 55recall base of old name 

c»@ren 55rename function 

@bdos 

5 5 rename complete 

n to 5 5 redefine rename 

h»fcb&o 55old fcb address 

dtfcb&n 55new fcb address 

irens jirename subroutine 

new told 



Set macro deu 
5! read character from deuice 
if @8=deu <= @lst 



Listing 9-28. (continued) 
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simple 


input 


fflui 


c >8fitdeu 


call 


§bdos 


else 




call 


det&deu 


endm 





put macro deu 

;; write character from ace urn to deuice 
if @&dev <= @lst 

5! simple output 

push psw lisave character 

tnvi c>@&deu iiwrite char function 

mou eta iireadx for output 

call @bdos 55write character 

pop psw 55restore for testing 

else 

call put&dev 

endm 



Listing 9-28. (continued) 



The equates that follow define the usual BDOS entry points and functions along 
with the disk sector size (@SECT) and special nongraphic characters (EOF, CR, LF, 
and TAB). The equates for @KEY through @LST are used in the GET and PUT 
macros to determine the source or destination device. The INFILE, OUTFILE, and 
SETFILE equates are used in the FILE macro as mnemonics for the file mode attribute. 

FILLNAM is a utility macro used in the construction of a File Control Block. 
FILLNAM accepts a filename or filetype along with a field size and builds a sequence 
of DBs that fill the name or type field with padded blanks. 

FILLDEF is a utility macro similar to FILLNAM, but FILLDEF fills the File Con- 
trol Block name or type field from the default File Control Block at @TFCB or 
@TFCB + 16. FILLDEF is invoked to extract either the default filename (first eight 
characters) or default filetype (following three-character field). 

The FILLDEF macro constructs an inline subroutine to perform the data move 
operation the first time it is invoked and calls the inline subroutine (@DEF) on 
subsequent invocations. 
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FILLNXT initializes two assembly time variables: @NXTB and @NXTD. @NXTB 
counts the accumulated size of buffers as they are automatically allocated in the FILE 
statement. @NXTD counts files in the FILE macro for later reference in GET and 
PUT statements. They are included within a macro, so that they are properly initial- 
ized in the two successive passes of the macro assembler. FILLNXT is invoked by 
the FILE macro where the expansion initializes @NXTB and @NXTD. FILLNXT 
then redefines itself as an empty macro, so that subsequent FILE invocations do not 
reset the two counters. 

The macro FILLFCB constructs a File Control Block in the CP/M standard format, 
where FID is the file identifier; DN is the disk name; FN is the filename; FT is the 
filetype; BS is the buffer size, and BA is the buffer address, as described in the FILE 
statement above. Recall that some of these parameters might be empty, causing 
default conditions to be selected. 

The FILLFCB macro begins by searching for a "1" or a "2" as the FN parameter, 
indicating that default name 1 or 2 is to be selected for the file. The IRPC loop 
involving ?C results in a value of 1 for @C if either FN = 1 or FN = 2, and a value 
of for @C if FN is not 1 or 2. The FILLFCB macro then selects either the default 
name or the user-specified name along with the default or user-specified drive num- 
ber. The equate for FCB&FID then produces the address of the File Control Block 
for the file identifier followed by DB for the extent field and DS 20 for the remain- 
der of the File Control Block. 

The remainder of the FILLFCB macro is devoted to storage allocation for buffer 
areas. The @BS variable is set to the buffer size after rounding and size checks. 
FID&BUF then becomes the address of the file buffer area, and FID&ADR labels a 
DW containing this literal value. FID&SIZ becomes the literal size of the buffer, and 
FID&cLEN labels a DW containing the literal size. FID&PTR is also allocated as a 
double byte that subsequently holds the buffer index of the next character to get or 
put in the file. All of these values are used in the file operations that occur later. 

The principal file access macro, FILE, sets up the File Control Block, buffers, and 
access subroutines for a file. Similar to the FILLFCB macro, the parameters FID, DN, 
FN, FT, BS, and BA describe the particular characteristics of a file. The MD param- 
eter, however, indicates the file mode and must have the value i, 2, or 3. The FILE 
macro begins by assigning the mode value to FID&TYP, so that subsequent macros 
can determine the type of access for this file. The FILLFCB macro is then invoked to 
construct the File Control Block for this macro and sets generally useful parameters 
for the file, as discussed previously. The FILE macro then generates the label GET&FID 
for input files or PUT&FID for output files, followed by a subroutine that GETs a 
single character or PUTs a single character for this file. 
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The GET&FID reads a single character from the input buffer and, when the 
input buffer is exhausted, fills the buffer area again in preparation for following GET 
operations. Upon detecting a real end-of-file, the EOF character is returned with the 
zero flag set. Similarly, the PUT&FID subroutine generated for output files stores the 
accumulator character into the output buffer at the next character position and, 
when the buffer is full, writes the sequence of sectors and returns to accept more 
output characters. In the case of an output error, the appropriate message is printed, 
and control transfers to FILERR, which usually remains at 0000H, causing a system 
reboot. 

The generated code that follows the label PSUB initializes the file pointers to the 
proper position for file access. The file extent and next record fields of the File 
Control Blocks are zeroed for both input and output files. In the case of an input 
file, the buffer index variable FID&cPTR is set to the end of the buffer, causing an 
immediate read operation when the first character is read. In the case of an output 
file, the FID&PTR is set to zero, indicating that the next position to fill is the first 
character of the output buffer. If the file is an output file, any duplicate files are 
erased, and a new file is created. In both cases, the file is opened upon completion of 
the FILE operation, and the buffer pointers are set for the next GET or PUT invoca- 
tion. Note that the FILE statement is executable; it must occur ahead of the GET or 
PUT statements for the file and performs its function each time control passes through 
the FILE machine code. 

The FINIS macro serves to empty the output buffers and close the file for output. 
Input files are skipped because no actions need take place to close an input file. The 
FINIS macro fills the remaining buffer segment (one size sector) with EOFs, then 
writes the partially filled buffers. 

The ERASE macro accepts a file identifier or list of file identifiers and successively 
calls the BDOS to erase each file, while the DIRECT macro searches for a single file 
given by the file identifier FID. In the case of the DIRECT macro, the zero flag is 
cleared if the file exists. No prechecks are made to see if the file exists before the 
ERASE operation takes place, although erasing a nonexistent file is of no conse- 
quence. The DIRECT macro can, of course, be used to check if a file exists before 
the ERASE is executed. 
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The RENAME macro allows a file to be renamed by accepting two file identifiers, 
denoted by NEW and OLD. These file identifiers must correspond to the FCB names 
created by FILLFCB in an earlier FILE invocation, and have the effect of renaming 
the OLD file to the NEW filename. This is accomplished within the RENAME macro 
through an inline subroutine, called @RENS, which is included the first time the 
RENAME macro is invoked. The inline subroutine moves the new File Control Block 
information (first sixteen bytes) into the second half of the old File Control Block in 
the form required for a rename operation under CP/M. (See the CP/M documenta- 
tion.) The BDOS is then called to perform the rename function. There is no check to 
ensure the old file exists before the rename takes place. 

The GET and PUT macros are similar in structure: both accept a device or file 
identifier as the formal parameter DEV and perform the corresponding input or 
output function on that device. If the device is a simple peripheral, the BDOS is 
called directly to perform the input and output function. If, instead, the device name 
was created by a FILE macro, the corresponding GET&FID or PUT&FID subroutine 
is called to accomplish the input or output operation. Note that the accumulator is 
preserved (PUSH PSW) upon output to a simple peripheral within the PUT macro; 
the save/restore sequence is performed within the PUT&FID subroutine if the desti- 
nation is a disk file. 

Listings 9-29 shows the full expansion of a segment of the case conversion pro- 
gram of Listing 9-27 (using the "+M" assembly parameter). It begins with the 
invocation of FILE, followed by FILLFCB, again followed by FILLDEF. The @DEF 
subroutine is included inline, and the FILLDEF macro is redefined to exclude the 
subroutine. Upon completion of the FCB construction, the file parameters are gener- 
ated, as shown in Listing 9-29b, along with the beginning of the GETSOURCE 
subroutine. 

The conditional assembly ignores the portions of this FILE macro expansion that 
are related to output files but includes the machine code for the input SOURCE file. 
In each case, the &FID labels result in names with the prefix or suffix SOURCE, 
associating the generated labels with this internal name. The machine code that 
initializes the File Control Block fields and buffer pointer follows the label ??0001. 
Upon completion of the FILE macro, the SOURCE file is ready for access. Each call 
to GETSOURCE reads one more character into the accumulator. Due to the length 
of the expanded macro form, the remainder of the case translation program is not 
shown. 
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To illustrate the facilities of the SEQIO macro library, two additional programs 
are given. The first, called PRINT, formats the output from the macro assembler for 
printing on the system line printer. The second, called MERGE, performs a simple 
merge operation on two disk files. 







FILE 


INFILE .SOURCE . .1 » .2000 


+ 




LOCAL 


PSUB.MSG.PMSG 


+ 




LOCAL 


PND»E0D.E0B»PNC 


0001+= 


S0URCETYP 


EQU INFILE 


+ 




FILLFCB 


SOURCE. .1 ..2000. 


+ 




LOCAL 


PFCB 


000 1+* 


@C 


SET 


1 


+ 




IRPC 


?C.l 


+ 




IF 


NOT ( '&?C = '1' OR '& 


+ 


ec 


SET 





+ 




ENDM 




+ 




IF 


NOT ( '1 ' = '1 ' OR '1' 


+ 


@c 


SET 





+ 




ENDM 




+ 




IF 


@C 


+ 




IF 


NUL 


oooc+* 


iC 


SET 


12 


+ 




ELSE 




+ 


@c 


SET 


9 


+ 




ENDIF 




+ 




FILLDEF 


FCBS0URCE»(l-l)*16i@C 


+ 




LOCAL 


PSUB 


0103+C30F01 




JMP 


??0009 


+ 


iDEF: 






010G+7E 




MOV 


A.M 


0107+12 




STAX 


D 


0108+23 




INX 


B 


0109+13 




INK 


D 


010A+OD 




DCR 


C 


010B+C20G01 




JN2 


@DEF 


010E+C9 




RET 




+ 


??0009 


: 




+ 


FILLDEF 


MACRO ?FCB»?F.?L 


+ 




LXI 


H.8TFCB+7F 


+ 




LXI 


D.7FCB 


+ 




MUI 


C»?L 


+ 




CALL 


iDEF 




Listing 9-29. 
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+ 




ENDM 




+ 




FILLDEF 


FCBSOURCEt(l-l)*lG»@C 


010F+Z15C00 




LXI 


Hi@TFCB+(l-l)*lG 


0112+111D01 




LXI 


D (FCBSOURCE 


0115+0E0C 




MVI 


C»iC 


0117+CD0601 




CALL 


iDEF 


+ 




ENDM 




+ 




ENDM 




011A+C34401 




JMP 


??000B 


011D+ 
+ 
0000+* 




DS 


@C 


iCNT 


SET 


12-iC 


+ 




IRPC 


?FCi 


+ 




IF 


BCNT=0 OR NUL ?FC 


+ 




EXITM 




+ 




ENDIF 




+ 




DB 


'8.7FC 


+ 


@CNT 


SET 


eCNT-1 


+ 




ENDM 




+ 




IF 


BCNT=0 OR NUL 


+ 




EXITM 




+ 




REPT 


@CNT 


+ 




DB 


' ' 


+ 




ENDM 




+ 




ENDM 




+ 




ELSE 




+ 




JMP 


770008 


+ 




IF 


NUL 


+ 




DB 





+ 




ELSE 




+ 




DB 


' ' = 'A' + 1 


+ 




ENDIF 




+ 




FILLNAM 


1 ,8 


+ 




FILLNAM 


>3 


+ 




ENDIF 




011D + = 


FCBSOURCE 


EOU $-12 


0129+00 




DB 





012A+ 




DS 


20 


+ 




IF 


SQURCETYP<=2 


+ 




FILLNXT 




0000+* 


HNXTB 


SET 





000G+* 


@NXTD 


SET 


iLST+1 


+ 


FILLNXT 


MACRO 


+ 




ENDM 





Listing 9-29. (continued) 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



203 



9.4 Operating System Interface Programmer's Utilities Guide 



+ 




ENDM 




+ 




IF 


2000+0<@SECT 


+ 


iBS 


SET 


@SECT 


+ 




ELSE 




0780+8 


@BS 


SET 


(2000/@SECT)*BSECT 


+ 




ENDIF 




+ 




IF 


NUL 


0370+8 


SOURCEBUF 


SET BUFFERS+iNXTB 


0780+8 


@NXTB 


SET 


@NXTB+iBS 


+ 




ELSE 




+ 


SOURCEBUF 


SET 


+ 




ENDIF 




+ 


SOURCEADR: 




013E+7003 




DW 


SOURCEBUF 


0780+= 


SOURCESIZ 


EQU @BS 


+ 


SOURCELEN: 




0140+8007 




DW 


@BS 


+ 


SOURCEPTR: 




0142+ 




DS 




000B+8 


@S0URCE 


SET iNXTD 


0007+8 


@NXTD 


SET 


@NXTD+1 


+ 




ENDIF 




+ 


??0008 


: 


ENDM 


+ 




IF 


INFILE=3 


+ 




EXITM 




+ 




ENDIF 




0144+C3B401 




JMP 


??0001 


+ 




IF 


INFILE=1 


+ 


GETSOURCE: 




+ 




ELSE 




+ 


PUTSOURCE: 




+ 




PUSH 


PSW 


+ 




ENDIF 




0147+2A4001 




LHLD 


SOURCELEN 


014A+EB 




XCHG 




014B+2A4201 




LHLD 


SOURCEPTR 


014E+7D 




MOV 


A»L 


014F+33 




SUB 


E 


0150+7C 




MOV 


A»H 


0151+3A 




SBB 


D 


0152+DA9D01 




JC 


??0007 


0155+210000 




LXI 


H»0 


0158+224201 




SHLD 


SOURCEPTR 
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??0004: 



015B+EB 


XCHG 




015C+2A4001 


LHLD 


SOURCELEN 


015F+7B 


MOV 


A.E 


0160+95 


SUB 


L 


01G1+7A 


MOV 


A,D 


01G2+9C 


SBB 


H 


01B3+D28F01 


JNC 


??000B 


0166+2A3E01 


LHLD 


SOURCEADR 


0169+19 


DAD 


D 


016A+EB 


XCHG 




016B+0E1A 


MVI 


C.0DMA 


016D+CD0500 


CALL 


iBDOS 


0170+1 11D01 


LXF 


D»FCBSOURCE 


+ 


IF 


INFILE=1 


0173+0E14 


MVI 


C,@FRD 


+ 


ELSE 




+ 


MVI 


CGFWR 


+ 


ENDIF 




0175+CD0500 


CALL 


iBDOS 


0178+B7 


ORA 


A 


0179+C28901 


JNZ 


??0005 


017C+118000 


LXI 


D.0SECT 


017F+2A4201 


LHLD 


SOURCEPTR 


0182+19 


DAD 


D 


0183+224201 


SHLD 


SOURCEPTR 


0186+C35B01 


JMP 


??0004 


+ 


??0005: 




+ 


IF 


INFILE=1 


0189+2A4201 


LHLD 


SOURCEPTR 


018C+224001 


SHLD 


SOURCELEN 


+ 


ELSE 




+ 


LOCAL 


EMSG 


+ 


MVI 


CiMSG 


+ 


LXI 


D.EMSG 


+ 


CALL 


iBDOS 


+ 


POP 


PSW 


+ 


JMP 


FILERR 


+ 


EMSG: DB 


CR.LF 


+ 


DB 


'disk full: SOURCE 


+ 


DB 


'$' 


+ 


ENDIF 
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??0006: 



018F+118000 


LXI 


D»@TBUF 


0192+0E1A 


My i 


C>iDMA 


0194+CD0500 


CALL 


iBDOS 


0197+210000 


LXI 


H»0 


019A+224201 


SHLD 


SOURCEPTR 


+ 


??0007: 




019D+EB 


XCHG 




019E+2A3E01 


LHLD 


SOURCEADR 


01A1+19 


DAD 


D 


01A2+EB 


XCHG 




+ 


IF 


INFILE=1 


01A3+2A4001 


LHLD 


SOURCELEN 


01AB+7D 


MOV 


A»L 


01A7+B4 


ORA 


H 


01A8+3E1A 


MVI 


A»EOF 


01AA+C8 


RZ 




01AB+1A 


LDAX 


D 


+ 


ELSE 




+ 


POP 


PSW 


+ 


STAX 


D 


+ 


ENDIF 




01AC+2A4Z01 


LHLD 


SOURCEPTR 


01AF+23 


INX 


H 


01B0+Z24201 


SHLD 


SOURCEPTR 


01B3+C8 


RET 




+ 


??0001: 




01B4+AF 


XRA 


A 


01B5+322901 


STA 


FCBSOURCE+12 


01B8_323D01 


STA 


FCBSOURCE+32 


01BB+218007 


LXI 


HtSOURCESIZ 


01BE+2Z4001 


SHLD 


SOURCELEN 


+ 


IF 


INFILE=1 


01C1+ZZ4201 


SHLD 


SOURCEPTR 


01C4+0E0F 


MVI 


C»@OPN 


+ 


ELSE 




+ 


LXI 


H»0 


+ 


SHLD 


SOURCEPTR 


+ 


MVI 


C»@DEL 


+ 


LXI 


D.FCBSOURCE 


+ 


CALL 


0BDOS 


+ 


MVI 


C0MAK 


+ 


ENDIF 
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01CB+111D01 




LXI 


D.FCBSOURCE 


01C9+CD0500 




CALL 


iBDOS 


01CC+3C 




INR 


A 


01CD+C2EC01 




JNZ 


??0003 


01D0+0E09 




MVI 


C.iMSG 


01D2+11DB01 




LXI 


D,??0002 


01D5+CD0500 




CALL 


@BD0S 


01D8+C30000 




JMP 


FILERR 


01DB+0D0A 


??0002 


: 


DB CR.LF 


+ 




IF 


INFILE=1 


01DD+6EBF20534F 




DB 


'no SOURCE file' 


+ 




ELSE 




+ 




DB 


'no dir space: SOURCE 


+ 




ENDIF 




01EB+24 




DB 


'$' 


+ 


??0003 


: 





ENDM 
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The PRINT program, shown in Listing 9-30, executes under the Console Com- 
mand Processor and takes the following form: 

PRINT filename 

where filename is the name of a previously assembled program. PRINT assumes that 
there is a PRN file on the disk and possibly a SYM file on the same disk drive. The 
PRN file is first printed, with a form-feed at the top of each 56-line page. If the SYM 
file exists, it is also printed using the same formatting. If the files are successfully 
printed, they are both erased from the disk. 

The PRINT program begins by saving the console processor stack, with the inten- 
tion of returning directly to the CCP without a system reboot. The input printer file 
is then defined with a FILE statement that specifies the internal name PRINT and 
obtains the filename from the console command line. The filetype, however, is set to 
PRN in this case. After performing an initial page eject, the program loops between 
the PRCYC (print cycle) and ENDPR (end print) labels by successively reading char- 
acters from the PRINT source and writing to the printer through the LISTING 
subroutine. On detecting an end-of-file character, control transfers to the ENDPR 
label where the PRN file is erased from the disk. 
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The program then checks for the presence of the SYM file by invoking the FILE 
macro with a SETFILE mode. This creates the proper File Control Block for the 
input file with type SYM but does not create buffers or open the file for access. 
Following the FILE macro, the DIRECT statement performs a directory search and, 
if the file is not present, control transfers to the ENDLST (end listing) label where 
execution terminates. 

If the SYM file exists, the program performs another page eject and then opens the 
SYM file for access. Note that the third FILE macro accesses the SYM file using the 
internal name SYMBOL but shares the buffer areas of the PRINT file. The PRINT 
file has been erased at this point, so the buffers are available. 

If the SYM file is present, the program loops between the SYCYCLE (symbol cycle) 
and ENDSY (end symbol) labels where characters are read from the SYMBOL file 
and again sent to the printer through the LISTING subroutine. Upon detecting the 
end-of-file, control passes to the ENDSY label where the SYM file is erased from the 
disk. If no errors occur, control eventually reaches the ENDLST label where the 
printer page is ejected. The entry stack pointer is then retrieved from OLDSP, and 
control returns to the Console Command Processor, completing execution of the 
PRINT program. 



0100 



ORG 100H 

MACLIB SEQIO iSEOUENTIAL I/O LIB 









PRINT 


THE X.PRN AND X.SYM FILES ON THE 








LINE 


PRINTER HITH PAGE FORMATTING, 


oooc 


= 


FF 


EQU 


0CH 5F0RM FEED 


0038 


= 


MAXLINE 


EQU 5G 5MAX LINES PER PAGE 






i 
5 


SAME 


THE ENTRY STACK POINTER 


0100 


210000 




LXI 


HtO 


0103 


39 




DAD 


SP 5ENTRY SP TO HL 


0104 


22CF03 




SHLD 


OLDSP 5SAME ENTRY SP 


0107 


31CF03 




LXI 


SP (STACK 5SET TO LOCAL STACK 


010A 




i 

5 


FILE 
READ 


INFILE»PRINT»»1 tPRN.1000 
THE PRINT FILE UNTIL END OF FILE 


01F2 


CDBA03 




CALL 


EJECT 5T0P OF PAGE 


01F5 




PRCYC: 


GET 


PRINT 


01F8 


FE1A 




CPI 


EOF 


01FA 


CA0302 




JZ 


ENDPR iSKIP IF END FILE 
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01FD 


CD5103 


CALL 


LISTING 


0200 


C3F501 


JMP 


PRCYC 






ENDPR: 5END OF 


PRINT FI 


0203 




ERA3E 


PRINT 






5 

; CHECK FOR THE OP 


020B 




FILE 


SETFILE, 


023A 




DIRECT 


SYMCHK 


0243 


CA3C03 


JZ 


ENDLST 






> 

! SYMBOL 


FILE IS P 


024G 


CDBA03 


CALL 


EJECT 


0249 




FILE 
5 

SYCYCLE: 


INFILE.S 


032B 




GET 


SYMBOL 


0329 


FE1A 


CPI 


EOF 


032B 


CA3403 


JZ 


ENDSY 


032E 


CDS 103 


CALL 


LISTING 


0331 


C32B03 


JMP 


SYCYCLE 



0334 



ENDSY: ERASE SYMBOL 







ENDLST 






iEND OF 


033C 


CD8A03 




CALL 




EJECT 


033F 


2ACF03 




LHLD 




OLDSP 


0342 


F9 




SPHL 






0343 


C9 




RET 










5 


UTILITY 


SUBROUTI 






LISTOUT: 












iSEND 


A 


SINGLE C 


0344 






PUT 




LST 


034C 


21D203 




LXI 




HtCHARC 


034F 


34 




INR 




M 


0350 


C9 




RET 







iWRITE TO LISTING DEU 
LE» DELETE IT 



TIONAL .SYM FILE 
SYMCHK »»1 tSYM 
ilS IT THERE? 
iSKIP SYMBOL IF SO 

RESENT, PAGE EJECT 

!T0 TOP OF PAGE 

YMBOL, ,1 fSYMilOOOtPRINTBUF 



5SKIP TO END ON EOF 
iSEND TO PRINTER 

;for another char 

iERASE .SYM FILE 

LISTING - EJECT AND RETURN 

IENTRY STACK POINTER 
iRESTORE STACK POINTER 
!T0 CCP 

NES 

HARACTER TO THE PRINTER 

.CHARACTER COUNTER 
.INCREMENT POSITION 
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LISTING: 












5WRITE CHARACTER 


FROM REG-A TO LIST 


0351 


FEOC 




CPI 


FF 


iFORM FEED? 


0353 


C25F03 




JNZ 


LISTO 




035G 


AF 




XRA 


A 


.CLEAR LINE COUNT 


0357 


32D103 




STA 


LINEC 




035A 


32D203 




STA 


CHARC 


.CLEAR TAB POSITION 


035D 


3E0C 




MUI 


A »FF 


5REST0RE FORM FEED 


035F 


FEOA 


LISTOs 


CPI 


LF 


5END OF LINE? 


0361 


C27403 




JNZ 


LIST1 




0364 


AF 




XRA 


A 


5CLEAR TAB POSITION 


0365 


32D203 




STA 


CHARC 




03G8 


21D103 




LXI 


H.LINEC 


iLINE COUNTER 


036B 


34 




INR 


M 


.INCREMENTED 


036C 


7E 




MOM 


AtM 


5CHECK FOR END OF PA' 


036D 


FE38 




CPI 


MAXLINE 


5LINE OUERFLOW? 


036F 


D8 




RC 




iRETURN IF NOT 


0370 


3600 




MUI 


M.O 


5CLEAR LINEC 


0372 


3E0C 




MUI 


A»FF 


.SEND PAGE EJECT 


0374 


FE09 


LIST1: 


CPI 


TAB 


.TAB CHARACTER? 


037G 


C28703 




JNZ 


LIST2 








! 


FEED 


BLANKS TO NEXT TAB POSITION 


0379 


3E20 


TABOUT 


: 


MUI 


A,' ' 


037B 


CD4403 




CALL 


LISTOUT 




037E 


3AD203 




LDA 


CHARC 


CHARACTER POSITION 


0381 


E607 




ANI 


7H 


.MOD 8 


0383 


C27903 




JNZ 


TABOUT 


.FOR ANOTHER BLANK 






i 


ON CHARACTER BOUNDARY 


0388 


C9 




RET 










LIST2: 


iSIMPLE CHARACTE 


R 


0387 


C34403 




JMP 


LISTOUT 


iPRINT AND RETURN 






EJECT: 


iPERFORM PAGE EJECT 


038A 


3E0C 




MUI 


A»FF 


5F0RM FEED 


038C 


C34403 


i 
i 


JMP 
DATA 


LISTOUT 
AREAS 




038F 




STACK: 


DS 


64 


532 LEUEL STACK 


03CF 




OLDSP: 


DS 


2 


.ENTRY STACK POINTER 


03D1 




LINEC: 


DS 


1 


;line counter 


03D2 




CHARC: 


DS 


1 


CHARACTER COUNTER 






BUFFERS: 






03D3 






END 
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The next program, MERGE, is more complicated. The MERGE program accepts 
two filenames as input, taking the general command form 

MERGE filename 

where filename is the name of a master file, with assumed filetype of MAS, as well as 
an update name with assumed filetype UPD. The files consist of varying length rec- 
ords, each of which starts with a six-character numeric sequence number followed 
by textual material and ends with a carriage return line-feed sequence. The lines of 
information in the master and update files are assumed to be in ascending numeric 
order according to their sequence numbers. The MERGE program reads these two 
files and merges the records together to form a new file consisting of numerically 
ascending, sequence-numbered lines. 

Upon completion of the merge operation, the newly merged file becomes the new 
master file. Update records are properly interspersed within the new master file 
according to the numeric order, and any update record that matches a master record 
results in replacement of the master record by the update record. Upon successful 
completion of the merge operation, the original master file is renamed to have the 
filetype MBK (master back-up), the original update file is renamed to the filetype 
UBK (update back-up), and the newly created file becomes the new MAS file. In this 
way, the operator can return to the back-up files in case of error, so that the source 
data is not destroyed. 



0100 






ORG 




100H 








! 


FILE 


MERGE PROGRAM 








MACLIB 


SEQI0 


iSEQUENTIAL FILE 1/0 


0000 


= 


BOOT 


ECU 




0000H 


5SYSTEM REBOOT 


0006 


= 


SEQSIZ 


EQU 




B 


SIZE OF THE SEQUENCE * 


03E8 


= 


USIZE 


EQU 




1000 


5UPDATE BUFFER SIZE 


03E8 


= 


MSIZE 


EQU 




USIZE 


5MASTER BUFFER SIZE 


07D0 


= 


NSIZE 


EQU 




USIZE+MSIZE 5NEW BUFF SIZE 


0100 


31EC05 


> 


LXI 




SP. STACK 




0103 


C3C801 




JMP 




START 


;to perform the merge 



UTILITY SUBROUTINES 



Listing 9-31. File Merge Program 
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DIGIT: 5TEST ACCUMULATOR FOR VALID DIGIT 
5 RETURN WITH CARRY SET IF INVALID 
010B FE30 CPI '0' 

0108 D8 RC .CARRY IF BELOW 

0109 FE3A CPI '9' +1 5CARRY IF BELOW 10 
010B 3F CMC 5N0 CARRY IF BELOW 10 
010C C9 RET 

5 

5 ERROR MESSAGES FOR READU AND READM 

SEOERRU: 
010D 7570G4E174 DB 'update seq error' >0 

SEQERRM: 
01 IE ED617374G5 DB 'master seq error' >0 

5 

! GENERATE READU AND READM SUBROUTINES 
IRPC ?F»UM 

5 INLINE SEQUENCE NUMBER BUFFER 

7F&SEQ: DB iTO START PROCESSING 
DS SEQSIZ-15REMAINING SPACE FOR SEQ# 



READ&7F: 








LXI 


H»?F&SEQ 




.SEQUENCE BUFFER 


MOV 


A,M 




5IS IT FF (END FILE)? 


INR 


A 




5FF BECOMES 00 


RZ 






.SKIP THE READ 


! READ 


THE SEQUENCE 


NUMBER 


PORTION 


MVI 


CSEQSIZ 




iSIZE OF SEQUENCE » 


RD&7F&0: 








PUSH 


H 




iSAME NEXT TO FILL 


PUSH 


B 




.SAME NUMBER COUNT 


GET 


7F&FILE 




iREAD THE FILE 


POP 


B 




iRECALL COUNT 


POP 


H 




.RECALL NEXT FILL 


CPI 


EOF 




SEND FILE? 


JZ 


E0F&7F 






CALL 


DIGIT 




.ASCII DIGIT? 


LXI 


D»SEQERR&?F 


5ERR0R MESSAGE 


JC 


SEQERR 




.SEQUENCE ERROR 


5 NO SEQUENCE ERROR 


i FILL 


NEXT DIGIT POSITION 


MOU 


M»A 






INX 


H 




iNEXT TO FILL 


DCR 


C 




iCOUNT=COUNT-l 


JNZ 


RD&7F&0 




5F0R ANOTHER DIGIT 


RET 






5END OF FILL 



Listing 9-31. (continued) 
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E0F8.7F: 



MVI 
STA 
RET 
ENDM 



5END OF FILE. SET SEQ# TO OFFH 

A.OFFH 

7F&.SEQ ?SE0» SET TO FF 



SEQERR: 



018F 1A 

0190 B7 

0191 CA0000 

0194 D5 
0195 
019D Dl 
019E 13 
019F C38F01 



WRITE ERROR MESSAGE FROM (DE) TIL 00 

LDAX D 

ORA A 

JZ BOOT 

OTHERWISE. MORE TO PRINT 



iWRITE TO CONSOLE 



PUSH 


D 


PUT 


CON 


POP 


D 


INX 


D 


JMP 


SEQERR 



IFOR MORE CHARS 



01A2 OEOG 
01A4 7E 
01A5 23 
01AG E5 
01A7 C5 
01A8 
01AB CI 
01AC El 
01AD OD 
01AE C2A401 
01B1 C9 



WRITESEQ: 

5WRITE THE SEQUENCE NUMBER GIVEN BY HL 
5T0 THE NEW FILE 



WRITO: 



MVI 


C.SEQSIZ 


5SIZE OF SEQ* 


MOV 


AiM 




INX 


H 


.NEXT TO GET 


PUSH 


H 


5 SAVE NEXT ADDR 


PUSH 


B 


5SAVE COUNT 


PUT 


NEW 


iWRITE TO NEW 


POP 


B 


iRECALL COUNT 


POP 


H 


5RECALL ADDRESS 


DCR 


C 


JC0UNT=C0UNT-1 


JNZ 


WRITO 


5F0R ANOTHER CHAR 


RET 







Listing 9-31. (continued) 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



213 



9.4 Operating System Interface 



Programmer's Utilities Guide 









COMPARE THE UPDATE 


SEQUENCE NUMBER WITH 








THE MASTER SEQUENCE 


NUMBER, SET: 










CARRY IF 


UPDATE 


< MASTER 










ZERO IF 


UPDATE 


= MASTER 










-ZERO IF 


UPDATE 


> MASTER 






COMPARE: 










01B2 


112F01 




LXI 


D,USEQ 






iUPDATE SEQ# 


01B5 


215F01 




LXI 


H»MSEQ 






iMASTER SEQ# 


01B8 


OEOB 




MV I 


CSEQSIZ 






.SEQUENCE SIZE 


01BA 


1A 


CLOOP: 


LDAX 


D 






5UPDATE DIGIT 


01BB 


BE 




CMP 


M 






5UPDATE-MASTER 


01BC 


D8 




RC 








5CARRY IF LESS 


01BD 


CO 




RNZ 








5NZERO IF GTR 






5 


ITEMS 


ARE THE SAME, 


CHECK FOR OFFH 


01BE 


FEFF 




CPI 


OFFH 






;end of file 


01C0 


C8 




RZ 








5B0TH ARE OFFH 


01C1 


13 




INX 


D 






5NEXT UPDATE 


01C2 


23 




INX 


H 






5NEXT MASTER 


01C3 


OD 




DCR 


C 






5COUNT DOWN 


01C4 


C2BA01 




JNZ 


CLOOP 






5FOR ANOTHER DIGIT 


01C7 


C9 




RET 








.ZERO FLAG IF EQUAL 



01C8 



START: 



MAIN PROGRAM STARTS HERE 



.UPDATE FILE, WITH ASSUMED .UPD TYPE 
FILE INFILE,UFILE,,1 ,UPD,USIZE 



02B0 



5MASTER FILE, WITH ASSUMED TYPE .MAX 
FILE INFILE,MFILE,,1 ,MAS,MSIZE 



038C 



iNEW FILE, TEMP,$$$ (RENAMED UPON EOF'S) 
FILE OUTFILE, NEW,, TEMP, *$$,NSIZE 



047D CD3501 CALL READU .INITIALIZE UPDATE RECORD 

0480 CDS501 CALL READM INITIALIZE MASTER RECORD 

MERGE: .MAIN MERGING LOOP 

0483 CDB201 CALL COMPARE 5CARRY SET IF UPDATE<MASTER 

0486 CAAD04 JZ SAME .ZERO IF IDENTICAL SEQ» 

0489 D2C804 JNC MASLOW iMASTER LOW? 



048C 212F01 
048F CDA201 



UPDATE SEQUENCE NUMBER IS LOW 

LXI H,USEQ 5C0PY SEQUENCE NUMBER 

CALL WRITESEQ5WRITE THE SEQUENCE * 



Listing 9-31. (continued) 
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ULOOP: iUPDATE RECORD TO NEW FILE 



0492 




GET 


UFILE 


0495 


F5 


PUSH 


PSW 


0,496 




PUT 


NEW 


0499 


Fl 


POP 


PSW 


049A 


FEOA 


CPI 


LF 


049C 


CAA704 


JZ 


ENDUP 


049F 


FE1A 


CPI 


EOF 


04A1 


CAA704 


JZ 


ENDUP 


04A4 


C39204 


JMP 


ULOOP 


04A7 


CD3501 ENDUP: CALL 


READU 


04AA 


C3B304 


JMP 


MERGE 



iCHARACTER TO A 
iSAUE IT 

iOUTPUT TO NEW FILE 
iRECALL CHARACTER 
iLINE FEED? 



iCYCLE IF NOT END REC 



5read another seo» 
;for another record 



SAME; 



5SEQUENCE NUMBERS ARE IDENTICAL 



04AD 


3A5F01 




LDA 


MSEC 


iCHECK FOR OFFH 


04B0 


FEFF 




CPI 


OFFH 




04B2 


CAE904 




JZ 


ENDMERGE 








5 


NOT THE 


SAME* DE 


LETE MASTER RECORD 


04B5 




DELMAS 


: 


GET 


MFILE 


04B8 


FE1A 




CPI 


EOF 


5END OF FILE? 


04BA 


CAC204 




JZ 


GETMAS 


5GET SEQ* ff 


04BD 


FEOA 




CPI 


LF 




04BF 


C2B504 




JNZ 


DELMAS 


5F0R ANOTHER CHAR 


04C2 


CDG501 


GETMAS 


: 


CALL 


READM !T0 NEXT RECORD 


04C5 


C38304 




JMP 


MERGE 


iFOR ANOTHER 






» 
MASLOW 


: 


iMASTER 


SEQUENCE NUMBER IS LOW 


04CB 


215F01 




LXI 


H.MSEO 




04CB 


CDA201 




CALL 


WRITESEQ 


5SEQUENCE NUMBER 


04CE 




ML00P: 


GET 


MFILE 




04D1 


F5 




PUSH 


PSW 


5SAVE MASTER CHARACTER 


04D2 






PUT 


NEW 




04D5 


Fl 




POP 


PSW 


iLF OR EOF? 


04DG 


FEOA 




CPI 


LF 




04D8 


CAE304 




JZ 


ENDMS 




04DB 


FE1A 




CPI 


EOF 




04DD 


CAE304 




JZ 


ENDMS 




04E0 


C3CE04 




JMP 


MLOOP 


iMORE TO COPY 


04E3 


CDS501 


i 
ENDMS: 


CALL 


READM 


iREAD NEW SEQ NUMBER 


04E6 


C38304 




JMP 


MERGE 


5T0 MERGE ANOTHER 



Listing 9-31. (continued) 
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04E9 



0529 
0558 



0560 



ENDMERGE: 

iCLOSE ALL FILES FOR RENAMING 

FINIS <UFILE»MFILE»NEW> 

50LD MASTER FILE FOR ERASE/RENAME 

FILE SETFILE»0LDMAS,,1 ,MBK 

ERASE OLDMAS 

5RENAME MASTER TO ,MBK 

RENAME OLDMAS .MFILE 



0580 
05AF 



)5B7 



.OLD UPDATE FILE FOR ERASE/RENAME 
FILE SETFILE»0LDUPD»»1 »UBK 
ERASE OLDUPD 
iRENAME UPDATE TO ,UBK 
RENAME OLDUPD .UFILE 







iRENAME NEW TO MASTER FILE 


05C0 




RENAME MFILE»NEW 


05C9 


C30000 


JMP BOOT 


05CC 




i 

DS 32 5 IS LEVEL STACK- 
STACK: 

5 BUFFER AREA 
BUFFERS: 


14GC 


= 


MEMSIZE EQU BUFFERS+NXTB 


05EC 




END 



Listing 9-31. (continued) 



The MERGE program, shown in Listing 9-31, begins with utility subroutines, 
including the DIGIT subroutine that tests for valid decimal digits in sequence num- 
bers. The IRPC that follows the DIGIT subroutine generates two distinct subroutines, 
called READU and READM, for reading the update and master files, respectively. 
The generation of these two subroutines has been suppressed in the listing to keep 
the listing short. (See Section 10.) These two READ subroutines fill their respective 
sequence number buffers from the input source, so that the merge operation can take 
place based on the current sequence number values. Upon detecting an end-of-file, 
the sequence number is set to 0FFH as a signal that the input source has been 
exhausted. 
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The SEQERR subroutine reports an error condition when a nonnumeric character 
is detected in the sequence number field. Although the error reporting is spartan, 
sequence errors are easily found using the TYPE command on the master or update 
file. The WRITESEQ subroutine is called whenever the source for the next record 
has been determined. The COMPARE subroutine determines the next source record 
(master or update) by comparing the buffered sequence numbers from left to right 
while they are equal. If a mismatch occurs in the sequence number scan, COMPARE 
returns with the carry flag and zero flag set to indicate which file holds the next 
source record. 

Execution of the MERGE program begins following the START label where the 
update, master, and new files are defined. The UFILE and MFILE sources are defined 
with the same buffer sizes, as determined by the earlier USIZE and MSIZE equates. 
Both take their primary name from the default value specified at the CCP level by 
the operator. The new file is created as a temporary, with filename TEMP and 
filetype $$$, but is renamed upon completion of the program to become the master 
file. 

The merge operation proceeds in Listing 9-31 as follows. First the READU and 
READM subroutines are called to fill the sequence number buffers. The loop between 
MERGE and ENDMERGE is then repetitively executed until the merge is complete. 
On each iteration of this loop, the COMPARE subroutine is called to compare the 
buffered sequence numbers. If the update sequence number is smaller than the master 
sequence number, it is moved to the new file, and data is copied from the update file 
to the new file until the end of the current record is encountered. Upon completion 
of the copy operation, the READU subroutine is called again to refill the update 
sequence number buffer. 

If the COMPARE subroutine instead detects equal sequence numbers, control 
transfers to the SAME label, where the master record is deleted. Alternatively, the 
COMPARE subroutine causes control to transfer to the MASLOW label when the 
master sequence number is lower than the update sequence number. In this case, the 
master sequence number and data record are copied to the new file in exactly the 
same manner as an update record. 
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Upon completion of the merge operation, indicated by an end-of-file in both the 
update and master files, control transfers to the ENDMERGE label where the files 
are closed and renamed. Following the FINIS statement, the previous MBK file (pos- 
sibly from an earlier execution) is erased so that the current master (MAS) can be 
renamed to the master back-up (MBK). Similarly, any previous UBK file is erased, 
and the current update file is renamed to become the new UBK file. Finally, the new 
file (TEMP.$$$) is renamed to become the new master file (MAS) before execution 
stops. 

Listing 9-32 shows an example of the files involved in a typical merge operation. 
In this application, the sequence numbers control the ordering of a list of names that 
is updated periodically. The NAMES.MAS file, which is the original master, is updated 
by merging with the NAMES. UPD file, also shown in the listing. The merge opera- 
tion is initiated by typing 

MERGE NAMES 

and, upon completion, produces the new NAMES.MAS shown in the righthand col- 
umn of Listing 9-32. 

The SEQIO library is typical of the interface you can construct to provide a higher 
level interface between assembly language programs and their operating environment. 
Although the library shown here performs only simple sequential file input/output, 
you can construct more comprehensive libraries for random access based on this 
library. 
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NAMES. MAS 




000100 


ABERCROMBIE. SIDNEY 




000200 


CARLSBAD* YOLANDA 




000300 


EGGBERT.EBENEZER 




000400 


GRAVELPAUGH. HORTENSE 


000100 


000500 


ISENEARS. IGNATZ 


000110 


OOOGOO 


KRABNATZ. TILLY 


000200 


000700 


MILLYWATZ, RICARDO 


000210 


000800 


OPFATZ, ADOLPHO 


000300 


000900 


QUAGMIRE* DONALD 


000330 


001000 


TWITSWEET, LADNER 


000400 


001090 


VERANDA i VERONICA 


000410 


001100 


WILLOWANDER. PRATNEY 


000500 


001200 


YUPPGANDER. MANNY 


000540 
000600 
OO0G2O 
000700 
000710 
000800 
000820 
000900 
000930 




NAMES. UPD 


0009GO 
001000 


000110 


BERNSWEIGER. ALFRED 


001010 


000200 


CRUENCE. CLARENCE 


001090 


000210 


DENNINGSKI » HUBERT 


001100 


000330 


FINKLESTEIN. FRANK 


001110 


000410 


HILLSENFIELDS. RANDOLPH 


001200 


000540 


JOLLYFELLOW, JUNE 


001210 



000G20 LAMBAA. WILLY 
000710 NEEBEND. ASTRID 
000820 PRATTWITZ, HEADY 
000930 RUBBLEMEYER. RUNYON 
0009B0 SWIGSTITTS. ULYSSES 
001010 UMPLANDER. XAVIER 
001110 XYLOPH. ERHARDT 
001210 ZEPLIPPS. EGGERWORTZ 



new NAMES. MAS 

ABERCROMBIE. SIDNEY 
BERNSWEIGER. ALFRED 
CRUENCE. CLARENCE 
DENNINGSKI . HUBERT 
EGGBERT. EBENEZER 
FINKLESTEIN. FRANK 
GRAVELPAUGH. HORTENSE 
HILLSENFIELDS. RANDOLPH 
ISENEARS. IGNATZ 
JOLLYFELLOW. JUNE 
KRABNATZ. TILLY 
LAMBAA, WILLY 
MILLYWATZ. RICARDO 
NEEBEND. ASTRID 
OPFATZ. ADOLPHO 
PRATTWITZ. HEADY 
QUAGMIRE. DONALD 
RUBBLEMEYER. RUNYON 
SWIGSTITTS, ULYSSES 
TWITSWEET, LADNER 
UMPLANDER. XAVIER 
UERANDA. VERONICA 
WILLOWANDER. PRATNEY 
XYLOPH. ERHARDT 
YUPPGANDER. MANNY 
ZEPLIPPS. EGGERWORTZ 



Listing 9-32. Sample MERGE Disk Files 



End of Section 9 
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Section 10 
Assembly Parameters 



You can include assembly parameters when you invoke the assembler that controls 
various assembler functions. The macro assembler is initiated with the name of the 
source file, followed by a dollar sign ($) and the assembly parameters. The parame- 
ters are indicated by single controls that denote particular functions. The character 
on the left below controls the function shown to the right. 



Table 10-1. Assembly Parameters 



Character 


Function 


A 


the source disk for the .ASM file 


H 


the destination of the .HEX machine code file 


L 


the source disk for the .LIB files (see MACLIB) 


M 


MACRO listings in the .PRN file 


P 


the destination of the .PRN file containing the listing 


Q 


the listing of LOCAL symbols 


S 


the generation and destination of the .SYM file 


1 


pass 1 listing 



Any or all of the above parameters can be included. The A, H, L, and S parameters 
are followed by the drive name to obtain or receive the data, where the drives are 
labeled A, B, . . . , Z. By convention, the X disk corresponds to the user's console; 
the P disk corresponds to the system line printer (logical list device), and the Z disk 
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corresponds to a null file that is not recorded. The following is a valid assembly 
parameter list following the MAC command and source filename: 

$PB AA HB SX 

that directs the .PRN file to disk B, reads the .ASM file from disk A, directs the 
.HEX file to the B disk, and sends the .SYM file to the user's console. Blanks are 
optional between parameter specifications. 

The parameters L, S, M, Q, and 1 can be preceded by + or - symbols that enable 
or disable their functions. These functions are 

+ L lists input lines read from the macro library (see MACLIB). 

— L suppresses listing of the macro library (default value). 

+ S appends the .SYM to the end of the .PRN output. 

— S suppresses the generation of the sorted Symbol Table. 

+ M lists all macro lines as they are processed during assembly. 

— M suppresses all macro lines as they are read during assembly. 
* M lists only hex generated by macro expansions. 

+ Q lists all LOCAL symbols in the symbol list. 

— Q suppresses all LOCAL symbols in the symbol list. 

+ 1 produces a listing file on first pass (for macro debugging). 

— 1 suppresses listing on pass 1 (default). 

The following is an example of a valid assembly parameter list that uses a number 
of the parameter specifications given above: 

$PB+S-M HB 

In this case, the .PRN file is sent to disk B with the symbol list appended (no .SYM 
file is created), all macro generations are suppressed, and the .HEX file is sent to disk 
B with the .PRN file. 
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The M parameter can be preceded by an asterisk (*), causing the assembler to list 
only macro generations that produce machine code. The asterisk suppresses the list- 
ing of the instructions that are produced; positions beyond the hex fields are not 
listed. Under normal operation, the macro assembler lists only generations that pro- 
duce machine code, along with the generated line. 

Given that disk d is the currently logged drive, the macro assembler defaults these 
parameters as follows: the .ASM and .LIB files are assumed to originate on drive d; 
the .HEX, .PRN, and .SYM files are sent to drive d; a Symbol Table is generated 
with LOCAL symbols suppressed. This means symbols beginning with ?? are not 
listed, and macro lines that generate machine code are listed. Note, however, that the 
filename following the MAC command can be preceded by a drive name, in which 
case the P parameter overrides the drive name, if supplied. Whenever a parameter is 
repeated in the assembly parameter specification, the last value is assumed. Valid 
assembly statements are shown below, assuming the file to be assembled is called 
SAMPLE. 

MAC SAMPLE *PX+S-M 

assembles the file SAMPLE.ASM with listing to the console, symbols at the console, 
and no listing of generated macros. 

MAC A:SAMPLE $+S -M+Q 

assembles sample.ASM from disk A, creating sample.PRN with appended symbols 
on the currently logged drive, suppressing generated macros, and listing symbols that 
begin with the characters ?? in addition to the usually listed symbols. 

MAC SAMPLE 

assembles SAMPLE.ASM from the currently logged drive, creating SAMPLE.PRN 
along with sample.SYM (containing the Symbol Table) and SAMPLE.HEX, which 
holds the Intel format hex file in the ASCII form. 
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MAC SAMPLE $AB HA PB +Q +S +L *M 

assembles the SAMPLE.ASM file from drive B and produces the file SAMPLE.HEX 
on drive A, with the SAMPLE.PRN file on drive B. The Symbol Table includes ?? 
symbols. The Symbol Table is placed at the end of the .PRN file on drive B. The .LIB 
files are listed with the .PRN file as the .LIB files are read. The instructions that 
correspond to generated macro lines are not included, although generated machine 
code is listed. 

In addition to the parameters shown above, you can intersperse controls through- 
out the assembly language source or library files. Interspersed controls are denoted 
by a $ in the first column of the input line, where the form shown on the left below 
corresponds to the action described on the right. 

$ - PRINT stops output listing by discarding formatted lines 

$ + PRINT enables the output printing when previously disabled 

$ — MACRO disables generated macro lines, as in - M above 

$ + MACRO enables full macro trace, as in + M above 

$ * MACRO enables partial macro trace, as in *M above 

Because MAC allows each line to be optionally prefixed by a line number, the $ 
control can be included directly following this line number. 

End of Section 1 
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Debugging Macros 



A number of common debugging practices can be used in developing macros and 
macro libraries. One technique, called iterative improvement, is often used in the 
design of programs and is most useful in building macros. The basic idea of iterative 
improvement is that a small portion of the overall macro set is first implemented and 
tested before continuing to more complicated macros. In this way, errors can be 
isolated at each step as the macro evolves. Further, if errors occur in the macro 
generations after a small portion of the macro set has been improved, it is most likely 
that the error is being caused by the macros that are changed. 

In the case of the Hornblower Highway System macro libraries, for example, 
iterative improvement was used to evolve the final macro library. Only the simplest 
macros were first implemented, including the SETLITE, TIMER, and RETRY macros. 
(See Section 9.) Debugging facilities were then added to these macros, so that the 
programs could be traced at the console. Upon successful testing of the basic macro 
facilities, the PUSH?, CLOCK?, and TREAD? macros were individually written and 
tested, resulting in the final macro library. 

At each step, you can use the various assembly parameters to control the debug- 
ging information. If the macro generations are not producing the proper machine 
code, it might be necessary to obtain a full trace, using the + M option when MAC 
is started. If the program produces too much output with the full trace enabled, you 
can use the $ + MACRO and $-MACRO commands interspersed throughout the 
assembly language source program, resulting in full macro generation traces only in 
the regions selected for debugging consideration. 

If macro generation errors are caused by macro libraries, you can use the +L 
parameter when MAC starts to cause the libraries to be included in the listing as 
they are read. 
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As a final consideration, it might be necessary to enable the first pass listing of the 
assembly language using the + 1 parameter. In this case, MAC lists the program as 
it is being read on the first pass as well as the second pass. Note, however, that the 
listing contains spurious error messages on this pass that might disappear on the 
second pass. The first pass listing parameter allows you to view the macro genera- 
tions on the two successive expansion passes to ensure that the assembler is process- 
ing the program in the same way in both cases. 

If a macro expands improperly, and the source of the error is not evident after 
examining various traces, it might be necessary to remove the offending macro from 
the program and create an isolated smaller test case where the error is reproduced. 
Full traces can then be examined to determine the source of the error and, after 
fixing the macro, it can be replaced in the larger program and retested. 



End of Section 1 1 
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Section 12 
Symbol Storage Requirements 



The maximum program size that can be assembled by MAC is determined only by 
the Symbol Table storage requirements for the program. The Symbol Table itself 
occupies the region above the macro assembler in memory, up to the base of the 
CP/M operating system. Thus, the size of the Symbol Table depends on the size of 
the current MAC version — approximately 12K program and data, plus 2.5K for I/O 
buffers — and the size of the user's CP/M configuration. The Symbol Table size is 
dynamically determined by MAC upon startup and fills as symbols are encountered. 
To provide some insight regarding storage requirements, the basic item size for iden- 
tifiers and macros is given below. 

A name used as a program label, data label, or variable in a SET or EQUATE 
requires 

N = L + 5 
bytes, where L is the length of the identifier name. Thus, the statement 
PORTVAL EQU 37FH 
makes an entry into the Symbol Table that occupies 

N = 7 + 5 = 12 bytes 

of Symbol Table space. Recall that LOCAL symbols take the form ??nnnn, which 
generates a name of length L = 6. 
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Macro storage is more complicated to compute. The general form is 

M = L + 7 + H + T 

where L is the macro name length; H is the parameter header storage requirement, 
and T is the macro text storage requirement, computed as 

H = Pj + P 2 + . . . + P n + n 

where Pj is the length of the first parameter name. The text length T is the number 
of characters in the macro body, including tab and end-of-line characters. Reserved 
symbols, however, are reduced to a single byte from their multicharacter representa- 
tions. The jump, call, and return on condition operators, however, require their full 
character representations. Comments starting with double semicolon are not included 
in the character count. The comment line is backscanned to remove preceding tab or 
blank characters in this case. For example, the macro 

LOADR MACRO REG >ALPHA 5FILL REGISTER crlf 
MUI REG ♦ '&ALPHA' 5 5DATA crlf 
ENDM crlf 

contains a macro header, followed by two macro lines, where each line is written 
with tab characters (rather than spaces) and terminated by carriage return line-feeds 
(crlfs). 

In this case, the macro name length (LOADR) is five characters (L = 5), and the 
parameter name lengths are three characters (REG) and five characters (ALPHA), 
resulting in the following parameter header storage requirement: 

H = P! + P 2 + 2 = 3 + 5 + 2 = 10 bytes 

The first macro line contains a leading tab (one byte), the MVI instruction (reduced 
to one byte), another tab character (one byte), the operands REG,'8cALPHA' (twelve 
characters), and the end of line (two characters), for a total of seventeen bytes. Note 
that the comment, with the preceding tab, is removed from the line. The second line 
contains a tab (one byte), ENDM (one byte), and end-of-line (two characters) for a 
total of four bytes. Summing the textual characters, the total is T = 21 bytes. As a 
result, the total macro storage for LOADP is 

M = L + 7 + H + T = 5 + 7 + 10 + 21 =43 bytes 
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No permanent storage is required for REPTs, IRPCs, or IRPs, although temporary 
storage in the Symbol Table is used while the groups are actively iterating. The 
characters contained within the group bounds (from the header to the corresponding 
ENDM) are stored in the Symbol Table in their literal form, with no reduction of 
reserved symbols to single bytes. Upon completion of the iteration, the storage is 
returned for other purposes. Similarly, active parameters for macro expansions require 
temporary storage in the Symbol Table. Storage is returned upon completion of the 
macro expansion. 

In any case, a Symbol Table overflow message results if the total amount of free 
Symbol Table space is used up. As mentioned previously, the user can regenerate the 
CP/M system, up to the maximum memory space of the 8080 processor, to increase 
the symbol table area. The percentage of Symbol Table utilization is always printed 
at the console at the end of assembly. The printout takes the form: 

OhhH USE FACTOR 

where hh is a hexadecimal value in the range 00 to FF, where 00 results from an 
almost empty table, and FF is produced from an almost full table. The value 08 OH, 
for example, is printed when the Symbol Table is half full. Keep note of the use 
factor as a program develops to gauge the relative amount of free space as the 
program is enhanced. 

In many of the examples shown in this manual, macros include inline subroutines 
that are generated at the first invocation and called upon subsequent invocations. 
(See the TYPEOUT macro in Listing 6-11, for example.) These subroutines can be 
included in the mainline program to reduce Symbol Table storage requirements, if 
necessary. In this case, the subroutines are assumed to exist the first time the macro 
is invoked, and thus are not generated by the macro. 



End of Section 12 
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Section 13 

RMAC, 

Relocating Macro Assembler 



RMAC, the CP/M Relocating Macro Assembler, is a modified version of the 
CP/M Macro Assembler (MAC). RMAC produces a relocatable object file (REL), 
rather than an absolute object file (HEX), that can be linked with other modules 
produced by RMAC, or by other language translators such as PL/I-80, to produce an 
absolute file ready for execution. The differences between RMAC and MAC are 
described in the following subsections. 



13.1 RMAC Operation 

RMAC takes the command form: 

RMAC filename.filetype 

followed by optional assembly parameters. If the filetype is not specified, ASM is 
assumed. RMAC produces three files: a list file (PRN), a symbol file (SYM), and a 
relocatable object file (REL). Characters entered in the source file in lower-case appear 
in lower-case in the list file, except for macro expansions. 

The assembly parameter H in MAC, used to control the destination of the HEX 
file, has been replaced by R, which controls the destination of the REL file. Directing 
the REL file to the console or printer (RX or RP) is not allowed, because the REL 
file does not contain ASCII characters. 

The following example directs RMAC to assemble the file TEST.ASM, send the 
PRN file to the console, and put the symbol file (SYM) and the relocatable object file 
(REL) on drive B. 

A>RMAC TEST $PX SB RB 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 231 



13.2 Expressions Programmer's Utilities Guide 

13.2 Expressions 

The operand field of a statement can consist of a complex arithmetic expression, 
as described in Section 3, with the following restrictions: 

■ In the expression A + B, if A evaluates to a relocatable value or an external, 
then B must be a constant. 

■ In the expression A-B, if A is an external, then B must be a constant. 

■ In the expression A-B, if A evaluates to a relocatable value, then B must be a 
constant, or B must be a relocatable value of the same relocation type as A. 
That is, both must appear in a CSEG or DSEG, or in the same COMMON 
block. 

■ In all other arithmetic and logical operations, both operands must be absolute. 

An expression error ('E') is generated if an expression does not follow these 
restrictions. 



13.3 Assembler Directives 

The following assembler directives have been added to support relocation and 
linking of modules: 

ASEG use absolute location counter 

CSEG use code location counter 

DSEG use data location counter 

COMMON use common location counter 

PUBLIC symbol can be referenced in another module 

EXTRN symbol is defined in another module 

NAME name of module 

The directives ASEG, CSEG, DSEG, and COMMON allow program modules to 
be split into absolute, code, data, and common segments. These segments can be 
rearranged in memory as needed at link time. The PUBLIC and EXTRN directives 
provide for symbolic references between program modules. 
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Note: symbol names can be up to 16 characters, but the first six characters of all 
symbols in PUBLIC, EXTRN, and COMMON statements must be unique, because 
symbols are truncated to six characters in the object module. 

13.3.1 The ASEG Directive 

The ASEG statement takes the form: 

label ASEG 

and instructs the assembler to use the absolute location counter until otherwise directed. 
The physical memory locations of statements following an ASEG are determined at 
assembly time by the absolute location counter, which defaults to and can be reset 
to another value by an ORG statement following the ASEG statement. 

13.3.2 The CSEG Directive 

The CSEG statement takes the form: 

label CSEG 

and instructs the assembler to use the code location counter until otherwise directed. 
This is the default condition when RMAC begins an assembly. The physical memory 
locations of statements following a CSEG statement are determined at link time. 

13.3.3 The DSEG Directive 

The DSEG statement takes the form: 

label DSEG 

and instructs the assembler to use the data location counter until otherwise directed. 
The physical memory locations of statements following a DSEG statement are deter- 
mined at link time. 

13.3.4 The COMMON Directive 

The COMMON statement takes the form: 

COMMON /identifier/ 

and instructs the assembler to use the COMMON location counter until otherwise 
directed. The physical memory locations of statements following a COMMON state- 
ment are determined at link time. 

ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 233 



13.3 Assembler Directives Programmer's Utilities Guide 

13.3.5 The PUBLIC Directive 

The PUBLIC statement takes the form: 

PUBLIC label{,label,...,label} 

where each label is defined in the program. Labels appearing in a PUBLIC statement 
can be referred to by other programs that are linked using LINK-80. 

13.3.6 The EXTRN Directive 

The EXTRN statement takes the form: 

EXTRN label{,label,...,label} 

The labels appearing in an EXTRN statement can be referenced but must not be 
defined in the program being assembled. They refer to labels in other programs that 
have been declared PUBLIC. 

13.3.7 The NAME Directive 

The NAME statement takes the form: 

NAME 'text string' 

The NAME statement is optional. It is used to specify the name of the relocatable 
object module produced by RMAC. If no NAME statement appears, the filename of 
the source file is used as the name of the object module. Module names identify 
modules within a library when using the LIB-80 library manager. 



End of Section 13 



234 ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Section 14 
XREF 



XREF is an assembly language cross-reference utility program used with the PRN 
and SYM files produced by MAC or RMAC to provide a summary of variable usage 
throughout the program. 

XREF takes the command form: 

XREF filename 

The filename refers to two input files that are created using MAC or RMAC with the 
assumed (and unspecified) filetypes of PRN and SYM, and one output file with an 
assumed (and unspecified) filetype of XRF. 

XREF reads the file, filename.PRN, line by line, attaches a line number prefix to 
each line, and writes each prefixed line to the file filename.XRF. During this process, 
XREF scans each line for any symbols that exist in the file filename.SYM. 

After completing this copy operation, XREF appends to the file filename.XRF a 
cross-reference report that lists all the line numbers where each symbol in file- 
name.SYM appears. It also flags with a # character each line number where the 
referenced symbol is defined. 

XREF also reports the value of each symbol, as it appears in the file filename.SYM. 

As an option, the file specification can include a drive name in the standard CP/M 
format, dr. When the drive name is specified, XREF associates all the files described 
above with the specified drive. Otherwise, it associates the files with the default drive. 
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XREF also allows you to direct the output file to the default list device instead of 
to the file filename.XRF. To use this option, add the string $p to the command line: 

XREF filename $P 

XREF allocates space for symbols and symbol references dynamically during exe- 
cution. If no memory is available for an attempted symbol or symbol reference 
allocation, XREF issues an error message and terminates. 

End of Section 14 
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Section 15 
LINK-80 



15.1 Introduction 

LINK-80 is a utility program you can use to combine relocatable object modules 
into an absolute file ready for execution under CP/M or MP/M II. 

There are two types of relocatable object modules. The first has a filetype of REL 
and is produced by PL/I- 80, RMAC, or any other language translator that produces 
relocatable object modules in the Microsoft® format. 

The second has a filetype of IRL and is generated by the CP/M library manager 
LIB-80. An IRL file contains the same information as a REL file but includes an 
index that enables faster searching of large libraries. 

Upon successful completion, LINK-80 lists the following items at the console: 

■ the Symbol Table 

■ any unresolved symbols 

■ a Memory Map 

■ the Use Factor 

The Memory Map shows the size and locations of the different segments. The Use 
Factor indicates the amount of available memory used by LINK-80 as a hexadecimal 
percentage. 

LINK-80 writes the Symbol Table to a SYM file suitable for use with the CP/M 
Symbolic Instruction Debugger (SID™) and creates a COM or PRL file for direct 
execution under CP/M or MP/M II. 
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15.2 LINK-80 Operation 

LINK-80 takes the general command form: 

link filename l{,filename2,. . ,,filenameN} 

where filenamel,. . .,filenameN are the names of the object modules to be linked. If 
you do not specify a filetype, LINK-80 assumes filetype REL. 

LINK-80 produces two files: 

■ filenamel.COM 

■ filenamel. SYM 

You can specify a different name for the COM and SYM files with a command of 
the form: 

link newfilename = filenamel{,filename2,. . .,filenameN} 

LINK-80 supports a number of optional switches that control the link operation. 
These switches are described in the following section. 

During the link process, LINK-80 can create up to eight temporary files on the 
default disk. The files are named: 

XXABS.**$ XXPROG*$$$ XXDATA*$$$ XXCOMM.$$$ 

YYABS.$$$ YYPROG*$$$ YYDATA.$$$ YYCOMM.$$$ 

LINK-80 deletes these files following termination. However, they can remain on the 
disk if LINK-80 halts due to an error condition. 

15.3 Multi-line Commands 

If a LINK-80 command does not fit on a single line (126 characters), the command 
can be extended by terminating the command line with an ampersand character. The 
ampersand can appear after any character in the command and need not follow a 
filename. 
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LINK-80 responds with an asterisk on the next line, at which point you can 
continue the command. LINK-80 allows any number of lines ending with the amper- 
sand. The last line terminates with a carriage return, as in the following example. 
The Symbol Table and memory map would appear where vertical ellipses are shown. 

to>linK main t iotnodlt iomodZt iotriod3t iomodtit iomodSt & 

LINK 1,3 

*libl[sJ* lihZLslt lib3[sJ, lib4& 

*fsJ> lasttrwd[p2000& : 

* tdZOOJ 



A> 

Note: you can use XSUB to submit multi-line commands to LINK-80. 

15.4 LINK-80 Switches 

LINK-80 supports optional run-time parameters called switches that control the 
link operation. All LINK-80 switches are enclosed in square brackets, separated by 
commas, and immediately follow one or more of the filenames in the command line. 

All switches except the S switch can appear after any filename in the command 
line. The S switch must follow the filename to which it refers. For example, 

A >LINK TESTEL40001 tlOMOD t TESTL IBCS ,NL tGSTARTl 

15.4.1 The Additional Memory (A) Switch 

The A switch provides additional space for Symbol Table storage by decreasing 
the size of LINK-80's internal buffers. Use this switch only when necessary, as indi- 
cated by a MEMORY OVERFLOW error. Using the A switch causes LINK-80 to 
store its internal buffers on the disk, slowing down the linking process considerably, 
while allowing linking of larger programs. 
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15.4.2 The BIOS Link (B) Switch 

The B switch is used to link a BIOS in a banked CP/M 3 system. LINK-80 aligns 
the data segment on a page boundary, puts the length of the code segment in the 
header, and defaults to the SPR filetype. 

15.4.3 The Data Origin (D) Switch 

The D switch specifies the origin of the data and common segments. If you do not 
use the D switch, LINK-80 places the data and common segments immediately after 
the program segment. 

The D switch takes the form: 

Dnnnn 

where nnnn is the data origin in hexadecimal. 

15.4.4 The Go (G) Switch 

The G switch specifies the label where program execution begins, if it does not 
begin with the first byte of the program segment. Using the G switch causes LINK- 
80 to put a jump to the label at the load address. 

The G switch takes the form: 

G<label> 

15.4.5 The Load Address (L) Switch 

The load address defines the base address of the COM file generated by LINK-80. 
The load address is usually 100H, which is the base of the Transient Program Area 
(TPA) in a standard CP/M system. The L switch also sets the program origin to 
nnnn, unless otherwise set by the P switch. 

The L switch takes the form: 

Lnnnn 

where nnnn is the desired load address in hexadecimal. 

Note: COM files created with a load address other than 100H do not execute prop- 
erly under a standard CP/M system. 
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15.4.6 The Memory Size (M) Switch 

The M switch can be used when you are creating PRL files to indicate that the 
program requires additional data space for proper execution. 

The M switch takes the form: 

Mnnnn 

where nnnn is the amount of additional data space needed in hexadecimal. 

15.4.7 The No List (NL) Switch 

The NL switch suppresses the listing of the Symbol Table at the console. 

15.4.8 The No Recording of Symbols (NR) Switch 

The NR switch suppresses the recording of the Symbol Table file on the disk. 

15.4.9 The Output COM File (OC) Switch 

The OC switch directs LINK-80 to produce a COM file. This is the default condi- 
tion for LINK-80. 

15.4.10 The Output PRL File (OP) Switch 

The OP switch directs LINK-80 to produce a page-relocatable PRL file rather than 
a COM file. See Section 7.1 of the MP/M II Operating System Programmer's Guide 
for more information on creating PRL files. 

15.4.11 The Output RSP File (OR) Switch 

The OR switch outputs RSP (Resident System Process) files for execution under 
MP/M. 

15.4.12 The Output SPR File (OS) Switch 

The OS switch outputs SPR (System Page Relocatable) files for execution under 
MP/M. 

15.4.13 The Program Origin (P) Switch 

The P switch specifies the origin of the program segment. If you do not use the P 
switch, LINK-80 puts the program segment at the load address, which is 100H unless 
otherwise specified by the L switch. 
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The P switch takes the form: 
Pnnnn 
where nnnn is the program origin in hexadecimal. 

15.4.14 The ? Symbol (Q) Switch 

Symbols in many run-time subroutine libraries begin with a question mark to 
avoid conflict with user-defined symbols. LINK-80 usually suppresses listing and 
recording of these symbols. 

The Q switch causes LINK-80 to include these symbols in the Symbol Table listed 
at the console and recorded on the disk. 

15.4.15 The Search (S) Switch 

The S switch indicates that the preceding file should be treated as a library. 
LINK-80 searches the file and includes only those modules containing symbols that 
are referenced but not defined in the modules already linked. 

15.5 The $ Switch 

The $ switch controls the source and destination devices. The $ switch takes the 
general form: 

$td 

where t is a type, and d is a drive specification. 

LINK-80 recognizes five types: 

■ C — Console 

■ I — Intermediate 

■ L — Library 

■ O— Object 

■ S — Symbol 
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The drive specification can be a letter in the range A through P corresponding to 
one of sixteen logical drives, or one of the following special characters: 

■ X — Console 

■ Y — Printer 

■ Z — Byte bucket 

15.5.1 $Cd - Console 

LINK-80 usually sends messages to the console, but messages can be directed to 
the list device by using $CY, or they can be suppressed by using $CZ. Once $CY or 
$CZ has been specified, $CX can be used subsequently in the command line to 
redirect messages to the console device. 

15.5.2 $Id - Intermediate 

LINK-80 usually places the intermediate files it generates on the default drive. The 
$1 switch allows you to specify another drive for intermediate files. 

15.5.3 $Ld - Library 

LINK-80 usually searches on the default drive for library files that are automati- 
cally linked because of a request item in a REL file. The $L switch instructs 
LINK-80 to search the specified drive for these library files. 

15.5.4 $Od - Object 

LINK-80 usually generates an object file on the same drive as the first REL file in 
the command line, unless an output file with an explicit drive is included in the 
command. The $0 switch instructs LINK-80 to place the object file on the drive 
specified by the character following the $0, or to suppress the generation of an 
object file if the character following the $0 is a Z. 

15.5.5 $Sd - Symbol 

LINK-80 usually generates a symbol file on the same drive as the first REL file in 
the command line, unless an output file with an explicit drive is included in the 
command. The $S switch instructs LINK-80 to place the symbol file on the drive 
specified by the character following the $S, or to suppress the generation of a symbol 
file if the character following the $S is a Z. 
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15.5.6 Command Line Specification 

The td character pairs following a $ switch must not be separated by commas. The 
entire group of $ switches must be set off from any other switches by a comma. For 
example, the three command lines shown below are equivalent: 

A>IinA' partlL$szt$odt$lbtnltpartZ 

A > I i n A' pa rt 1 [$szod 1 b m 1 tpa rtZ 

A>link partlC$sz od lbl t pa rtZtil 

The $1 switch specifies the drive to be used for intermediate files during the entire 
link operation, but the other $ switches can be changed in the command line. The 
value of a $ switch remains in effect until it is changed as LINK-80 processes the 
command line from left to right. This is especially useful when linking overlays. (See 
Section 16.) For example, the command 

A>Iin/f root (oul[$szczJ)(ov2)(ov3)(ov4[$sacxJ) 

suppresses the SYM files and console output generated when OV1, OV2 and OV3 
are linked. When OV4 is linked, LINK-80 places the SYM file on drive A and sends 
any messages to the console device. 



15.6 Creating MP/M II PRL Files 

Assembly language programs often contain references to symbols in the Base Page 
such as BOOT, BDOS, DFCB, and DBUFF. To run properly under CP/M, or as a 
COM file under MP/M II, these symbols are simply defined in equates as follows: 

5 Jump to warm boot 

i jump to bdos entry point 

Udefault file control block 

»default i/o buffer 

With PRL files, however, the Base Page itself can be relocated at load time, so 
LINK-80 must know that these symbols, while at fixed locations within the Base 
Page, are relocatable. 



boot 


equ 





bdos 


e^u 


5 


dfcb 


e«=iu 


5ch 


dbuf f 


e«=iu 


80 h 
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To do this, simply declare these symbols as externals in the modules in which they 
are referenced: 

extrn boot* bdos» d f c b » dbuff 

arid link in another module in which they are declared as publics and defined in 
equates: 

public boot* bdos > d c f b » dbuff 

boot e <=» u 5Jump to warm boot 

bdos eiu 5 5Juwp to bdos entry point 

dfcb e<=iu 5 c h 5 d e f a u 1 1 file control blocK 

dbuff equ 80 h idefaulti/o buffer 

end 



15.7 The Request Item 

Many language translators use the request item, a specific bit pattern in a REL file, 
to tell LINK-80 to search the appropriate run-time subroutine library file. When 
LINK- 80 processes a library request, it first searches for an IRL file with the specified 
filename. If there is no IRL file, it searches for a REL file of that name. If both 
searches fail, then LINK-80 displays the following error message and halts. 

NO FILE: filename.REL 

Libraries requested in this manner appear in the Symbol Table listed at the console 
with a value of 'RQST'. 
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15.8 REL File Format 

REL files contain information encoded in a bit stream, which LINK-80 interprets 
as follows: 

■ If the first bit is a 0, then the next 8 bits are loaded according to the value of 
the location counter. 

■ If the first bit is a 1, then the next 2 bits are interpreted as follows: 

00 — special link item, defined below. 

01 — program relative. The next 16 bits are loaded after being offset by 

the program segment origin. 

10 — data relative. The next 16 bits are loaded after being offset by the 

data segment origin. 

11 — common relative. The next 16 bits are loaded after being offset by 

the origin of the currently selected common block. 

■ A special item consists of: 

♦ A 4-bit control field that selects one of 16 special link items described 
below. 

♦ An optional value field that consists of a 2-bit address field and a 16- 
bit address field. The address type field is interpreted as follows: 

00 — absolute 

01 — program relative 

10 — data relative 

11 — common relative 

♦ An optional name field that consists of a 3-bit name count followed 
by the name in 8 -bit ASCII characters. 

The following special items are followed by a name field only. 

0000 — entry symbol. The symbol indicated in the name field is defined in this 

module, so the module should be linked if the current file is being 
searched, as indicated by the S switch. 

0001 — select common block. Instructs LINK-80 to use the location counter 

associated with the common block indicated in the name field for 
subsequent common relative items. 
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0010 — program name. The name of the relocatable module. 

0011 — unused. 

0100 — unused. 

The following special items are followed by a value field and a name field. 

0101 — define common size. The value field determines the amount of memory 

reserved for the common block described in the name field. The first 
size allocated to a given block must be larger than or equal to any 
subsequent definitions for that block in other modules being linked. 

0110 — chain external. The value field contains the head of a chain that ends 

with an absolute 0. Each element of the chain is replaced with the 
value of the external symbol described in the name field. 

0111 — define entry point. The value of the symbol in the name field is defined 

by the value field. 

1000 — unused. 

The following special items are followed by a value field only. 

1001 — external plus offset. The following two bytes in the current segment 

must be offset by the value of the value field after all chains have been 
processed. 

1010 — define data size. The value field contains number of bytes in the data 

segment of the current module. 

1011 — set location counter. Set the location counter to the value determined 

by the value field. 

1100 — chain address. The value field contains the head of a chain that ends 

with an absolute 0. Each element of the chain is replaced with the 
current value of the location counter. 

1101 — define program size. The value field contains the number of bytes in 

the program segment of the current module. 
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1110 — end module. Defines the end of the current module. If the value field 
contains a value other than absolute 0, it is used as the start address 
for the program being linked. That is, the current module is the main 
module. The next item in the file starts at the next byte boundary. 

Item 1111, end file, has no value field or name field. This item follows the end 
module item of the last module in the file. 



15.9 IRL File Format 

An IRL file consists of three parts: a header, an index, and a REL section. 
The header contains 128 bytes, defined as follows: 

■ byte — extent number of first record of REL section 

■ byte 1 — record number of first record of REL section 

■ bytes 2-127 — currently unused 

The index consists of a number of entries corresponding to the entry symbol items in 
the REL section. The entries take the form: 



e 


r 


b 


cl 


c2 




en 


d 



Figure 15-1. IRL File Index 

where: 

e = extent offset from start of REL section to start of module, 
r = record offset from start of extent to start of module, 
b = byte offset from start of record to start of module, 
cl-cn = name of symbol, 
d = end of symbol delimiter (OFEH). 
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The index terminates with an entry in which cl = OFFH. The remainder of the 
record containing the terminating entry is unused. 

The REL section contains the relocatable object code, as described in Section 15.8. 

End of Section 15 
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16.1 Introduction 

You can use LINK-80 to produce a simple tree structure of overlays as shown in 
Figure 16-1. Currently, the Overlay Manager is part of the PL/I-80 run-time library. 



OV5 OV6 



M 



OV1 OV2 OV3 OV4 

I I I I 

ROOT 
Figure 16-1. Tree-structured Overlay System 



In such a system, LINK-80 produces the ROOT.COM and ROOT.SYM files, as 
well as an OVL file and a SYM file for each overlay specified in the command line. 

The OVL file consists of a 256-byte header containing the load address and length 
of the overlay, followed by the absolute object code. The SYM file contains only 
those symbols that have not been declared in another module lower in the tree. 

The origin of an overlay is the highest address, rounded to the next 128-byte 
boundary, of the module below it on the tree. The stack and free space for the PL/I 
program are located at the top of the highest overlay which is, again, rounded to the 
next 128-byte boundary. LINK-80 displays this address at the console on completion 
of the entire link process and patches it into the root module in the location 'PMEMRY'. 
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The following restrictions must be observed when producing a system of overlays 
for a PL/I program using LINK-80: 

■ Each overlay has only one entry point. The Overlay Manager in the PL/I Run- 
time system assumes that this entry point is at the base (load address) of the 
overlay. 

■ No upward references are allowed from a module to an entry point in an 
overlay higher on the tree. The only exception is a reference to the main entry 
point of the overlay, as described above. Downward references to entry points 
in overlays lower on the tree or in the root module are allowed. 

■ The overlays are not relocatable, so the root module must be a COM file. 

■ Common blocks, EXTERNALS in PL/I, that are declared in one module can- 
not be initialized by a module higher in the tree. LINK-80 ignores any attempt 
to do so. 

■ Overlays can be nested to 5 levels. 

■ The Overlay Manager uses the default buffer located at 80H, so user pro- 
grams should not depend on data stored in this buffer. 

16.2 Using Overlays in PL/I Programs 

There are two ways to use overlays in a PL/I program. The first method is straight- 
forward and suffices for most applications. However, it has two restrictions. First, all 
overlays must be on the default drive, and second, the overlay names cannot be 
determined at run-time. 

The second method does not have these restrictions, but its calling sequence is 
slightly more complicated. 

16.2.1 Overlay Method 1 

To use the first method, simply declare an overlay as an entry constant in the 
module where it is referenced. As an entry constant, it can have parameters declared 
in a parameter list. The overlay itself is simply a PL/I procedure or group of procedures. 
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For example, the following program is a root module having one overlay: 

root: procedure options (main) 5 

declare ovl entry (char (15)) 5 
put skip list ( ' root ' ) 5 
call ovl ('overlay 1 ' ) » 
end root? 

with the overlay OV1.PLI defined as follows: 

oul: procedure ( c ) i 

declare c char (15)5 
put skip list ( c ) 5 
end o v 1 5 

Note: when passing parameters to an overlay, you must ensure that the number and 
type of the parameters are the same in the calling program and the overlay itself. 

To link these two programs into an overlay system, use the command: 

A>LI/W ROOT (OV1) 

This causes LINK-80 to produce four files: 



At execution time, ROOT.COM first displays the message 'root' at the console. 
The 'call ovl' statement then transfers control to the Overlay Manager. 

The Overlay Manager loads the file OVl.OVL from the default drive at the proper 
location above ROOT.COM and transfers control to it, passing the CHARAC- 
TER^) parameter in the usual manner. 

The overlay then executes, displaying the message 'overlay 1' at the console. It 
then returns directly to the statement following the 'call ovl' in ROOT.PLI, and 
execution continues from that point. 

If the Overlay Manager determines that the requested overlay is already in mem- 
ory, then it does not reload the overlay before transferring control to it. 
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There are several important points to keep in mind regarding overlay method 1 : 

■ The name associated with the overlay in the call and entry statements is th< 
actual name of the OVL file loaded by the Overlay Manager, so the twc 
names must agree. Because PL/I truncates symbol names to 6 characters in th( 
REL file, the names of the OVL files must be limited to 6 characters. 

■ The name of the entry point to an overlay (the name of the procedure) neec 
not agree with the name used in the calling sequence. The same name shoulc 
be used to avoid confusion. 

■ The Overlay Manager loads overlays only from the drive that was the default 
drive when the root module began execution. The Overlay Manager disre- 
gards any changes in the default drive that occur after the root module begins 
execution. 

■ The names of the overlays are fixed. This means the source program must be 
edited, recompiled, and relinked to change the names of the overlays. 

■ No nonstandard PL/I statements are needed. Thus the program is transportable 
to other systems. 

16.2.2 Overlay Method 2 

In some applications, it is useful to have greater flexibility with overlays, such as 
the ability to load overlays from different drives, or the ability to determine the name 
of an overlay at run-time, perhaps from the keyboard or from a disk file. 

To do this, a PL/I program must declare an explicit entry point into the Overlay 
Manager as follows: 

declare ? o u 1 a y entry (char ( 1 ) » fixed ( 1 ) ) 5 

The first parameter is a character string specifying the name of the overlay to load 
and an optional drive name in the standard CP/M format, d: filename. 

The second parameter is the Load Flag. If the Load Flag is 1, the Overlay Manager 
loads the specified overlay whether or not it is already in memory. If the Load Flag 
is 0, then the Overlay Manager loads the overlay only if it is not already in memory. 
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The 'call Povlay' statement signals the Overlay Manager to load the requested 
overlay, if needed. The Overlay Manager returns to the calling program, which must 
then perform a dummy call to execute the overlay just processed by the Overlay 
Manager. This allows a parameter list to be passed to the overlay. 

Using this method, the example shown in the first method above appears as follows: 

root: procedure options (main)? 

declare ? o u 1 a y entry (char (10) t fixed ( 1 ) ) 5 

declare dummy entry (char ( 1 5 ) ) 5 

declare name char (10)? 

put skip list ('root')? 

name = '001'? 

call ? o u 1 a v (name* 0)5 

call dummy ('ouerlay l')5 

end root? 

The file OV1.PLI is the same as before. 

At run-time, the Overlay Manager loads OVl.OVL from the default drive because 
that is the current value of the variable 'name', and then returns to the calling 
program, in this case, 'root.' 

At this point, the argument 'overlay 1' is set up according to the PL/I parameter 
passing conventions. The 'call dummy' statement transfers control to the Overlay 
Manager, which in turn transfers control to the base address of the overlay the name 
of which it just processed. When OV1 finishes execution, it returns to the statement 
following the call dummy statement. 

Note that in this example, name is set to 'OV1' in an assignment statement. 
However, the overlay name can also be supplied as a character string from some 
other source, such as the console keyboard. 
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Observe these important points when using overlay method 2: 

■ A drive name can be specified, so the Overlay Manager can load overlays 
from drives other than the default drive. If no drive is specified, the Overlay 
Manager uses the default drive as described in Method 1. 

■ The name of the overlay can be up to 8 characters in length because it is 
specified in the character string and not by the entry symbol. 

■ If there are any parameters in the dummy call following the call ?ovlay, they 
must agree in number and type with the parameters in the procedure declara- 
tion in the overlay. 

16.3 Specifying Overlays in the Command Line 

The syntax for specifying overlays is similar to that for linking without overlays, 
except that each overlay specification is enclosed in parentheses. 

An overlay specification can take one of the following forms: 

A>LINK ROOT(OVl) 

A>LINK R00T(0V1 *PART2 >PART3) 

A>LINK ROOT ( OV 1= PART 1 tPARTZ tPART3 ) 

The first command produces the file OVl.OVL from a file OV1.REL. The second 
command produces the file OVl.OVL from OV1.REL, PART2.REL, and PART3.REL. 
The third command produces the file OVl.OVL from PARTI. REL, PART2.REL, 
and PART3.REL. 
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Note that a left parenthesis, indicating the start of a new overlay specification, also 
indicates the end of the group preceding it. Thus the following command line is 
invalid, and LINK-80 flags it as an error: 

A>LINK ROOT(OVl) tMOREROOT 

All files to be included at any point on the tree must appear together, without any 
intervening overlay specifications. Thus the following command is valid: 

f\>LINK ROOT tMOREROOT (0V1) 

Any filename in the command line can be followed by a number of LINK-80 
switches. The overlay specifications are not set off from the root module or from 
each other with commas. Spaces can be used to improve readability. 

To nest overlays, they must be specified in the command line with nested parenthe- 
ses. For example, the following command line can link the overlay system shown in 
Figure 16-1: 

to>LINK ROOT (0V1) (0V2 (0V5) (0V6)) (0V3) (0V4) 



16.4 Sample LINK-80 Execution 

Listing 16-1 shows the console output from a LINK-80 operation. Note that OV1 
is flagged as an undefined symbol. LINK-80 indicates that OV1 has not been defined 
in the current module and assumes it is either the name of an overlay or a dummy 
entry point to an overlay. 

When linking overlays, each entry variable that refers to an overlay, by actual 
name or a dummy entry, appears as an undefined symbol. No symbols other than 
these actual or dummy overlay entry points should be undefined. 

Listing 16-2 shows the console output when executing the resulting COM file. 
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A > I i n k root(ovl) 
LINK 1.3 

PLILIB RQST ROOT 0100 /SYS IN/ 1A15 /SYSPRI/ 1A3A 

UNDEFINED SYMBOLS: 

001 

ABSOLUTE 0000 

CODE SIZE 18BC (0100-1SBB) 

DATA SIZE 02A9 (1A90-1D38) 

COMMON SIZE 00D4 (19BC-1A8F) 

USE FACTOR 4E 



LINKING 0U1.0UL 

PLILIB RQST 

ABSOLUTE 0000 

CODE SIZE 002a (1D80-1DA3) 

DATA SIZE 0002 (1DA4-1DA5) 

COMMON SIZE 0000 

USE FACTOR 09 

MODULE TOP 1E00 

Listing 16-1. LINK-80 Console Interaction 

f\> root 

root 

overlay 1 

End of Execution 

A> 

Listing 16-2. Console Interaction with ROOT 
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Error Messages 



At run-time, the Overlay Manager can display certain error messages. These mes- 
sages and a brief explanation of their causes are shown in Table D-l. 



Table D-l. Run-time Error Messages 



Error Cause 



ERROR (8) OVERLAY t NO FILE d : f i 1 en awe ♦ OML 

The Overlay Manager cannot find the indicated file. 



ERROR (9) OVERLAY* DRIVE d : f i 1 ename . OML 

An invalid drive code was passed as a parameter to Povlay. 



ERROR (10) OVERLAY, SIZE d: filename. OML 

The indicated overlay would overwrite the PL/I stack and/or free 
space if it were loaded. 



ERROR (11) OMERLAY » NESTING d : f i 1 en ame . OML 

Loading the indicated overlay would exceed the maximum nesting 
depth. 



ERROR (12) OVERLAY* READ d: filename. OVL 

Disk read error during overlay load, probably caused by premature 
EOF. 



End of Appendix D 
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During the course of operation, LIB-80 can display error messages. These error 
messages and a brief explanation of their causes are given in Table E-l. 



Table E-l. LIB-80 Error Messages 



Error 


Cause 


CANNOT CLOSE: 


LIB-80 cannot close the output file. The disk might 




be write-protected. 


DIRECTORY FULL: 


There is no directory space for the output file. 


DISK READ ERROR: 


LIB-80 cannot read the file properly. 


DISK WRITE ERROR: 


LIB-80 cannot write to the file properly, probably 




due to a full disk. 


FILE NAME ERROR: 


The form of a source filename is invalid. 


NO FILE: 


LIB-80 cannot find the indicated file. 


NO MODULE: 


LIB-80 cannot find the indicated module. 


SYNTAX ERROR: 


The LIB-80 command line is not properly formed. 



End of Appendix E 



ALL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



277 



Appendix F 
8080 CPU Instructions 







Table F-l 


. 8080 CPU Instructions 






OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


00 


NOP 




ID 


DCR 


E 


3A 


LDA 


Adr 


01 


LXI 


B,D16 


IE 


MVI 


E,D8 


3B 


DCX 


SP 


02 


STAX 


B 


IF 


RAR 




3C 


INR 


A 


03 


INX 


B 


20 


— 




3D 


DCR 


A 


04 


INR 


B 


21 


LXI 


H,D16 


3E 


MVI 


A,D8 


05 


DCR 


B 


22 


SHLD 


Adr 


3F 


CMC 




06 


MVI 


B,D8 


23 


INX 


H 


40 


MOV 


B,B 


07 


RLC 




24 


INR 


H 


41 


MOV 


B,C 


08 


— 




25 


DCR 


H 


42 


MOV 


B,D 


09 


DAD 


B 


26 


MVI 


H,D8 


43 


MOV 


B,E 


0A 


LDAX 


B 


27 


DAA 




44 


MOV 


B,H 


OB 


DCX 


B 


28 


— 




45 


MOV 


B,L 


OC 


INR 


C 


29 


DAD 


H 


46 


MOV 


B,M 


OD 


DCR 


C 


2A 


LHLD 


Adr 


47 


MOV 


B,A 


OE 


MVI 


C,D8 


2B 


DCX 


H 


48 


MOV 


C,B 


OF 


RRC 




2C 


INR 


L 


49 


MOV 


C,C 


10 


— 




2D 


DCR 


L 


4A 


MOV 


C,D 


11 


LXI 


D,D16 


2E 


MVI 


L,D8 


4B 


MOV 


C,E 


12 


STAX 


D 


2F 


CMA 




4C 


MOV 


C,H 


13 


INX 


D 


30 


— 




4D 


MOV 


C,L 


14 


INR 


D 


31 


LXI 


SP,D16 


4E 


MOV 


C,M 


15 


DCR 


D 


32 


STA 


Adr 


4F 


MOV 


C,A 


16 


MVI 


D,D8 


33 


INX 


SP 


50 


MOV 


D,B 


17 


RAL 




34 


INR 


M 


51 


MOV 


D,C 


18 


— 




35 


DCR 


M 


52 


MOV 


D,D 


19 


DAD 


D 


36 


MVI 


M,D8 


53 


MOV 


D,E 


1A 


LDAX 


D 


37 


STC 




54 


MOV 


D,H 


IB 


DCX 


D 


38 


— 




55 


MOV 


D,L 


1C 


INR 


E 


39 


DAD 


SP 


56 


MOV 


D,M 
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Table F-l. 


(continued) 








OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


57 


MOV 


D,A 


7B 


MOV 


A,E 


9F 


SBB 


A 


58 


MOV 


E,B 


7C 


MOV 


A,H 


A0 


ANA 


B 


59 


MOV 


E,C 


7D 


MOV 


A,L 


Al 


ANA 


C 


5A 


MOV 


E,D 


7E 


MOV 


A,M 


A2 


ANA 


D 


5B 


MOV 


E,E 


7F 


MOV 


A,A 


A3 


ANA 


E 


5C 


MOV 


E,H 


80 


ADD 


B 


A4 


ANA 


H 


5D 


MOV 


E,L 


81 


ADD 


C 


A5 


ANA 


L 


5E 


MOV 


E,M 


82 


ADD 


D 


A6 


ANA 


M 


5F 


MOV 


E,A 


83 


ADD 


E 


A7 


ANA 


A 


60 


MOV 


H,B 


84 


ADD 


H 


A8 


XRA 


B 


61 


MOV 


H,C 


85 


ADD 


L 


A9 


XRA 


C 


62 


MOV 


H,D 


86 


ADD 


M 


AA 


XRA 


D 


63 


MOV 


H,E 


87 


ADD 


A 


AB 


XRA 


E 


64 


MOV 


H,H 


88 


ADC 


B 


AC 


XRA 


H 


65 


MOV 


H,L 


89 


ADC 


C 


AD 


XRA 


L 


66 


MOV 


H,M 


8A 


ADC 


D 


AE 


XRA 


M 


67 


MOV 


H,A 


8B 


ADC 


E 


AF 


XRA 


A 


68 


MOV 


L,B 


8C 


ADC 


H 


B0 


ORA 


B 


69 


MOV 


L,C 


8D 


ADC 


L 


Bl 


ORA 


C 


6A 


MOV 


L,D 


8E 


ADC 


M 


B2 


ORA 


D 


6B 


MOV 


L,E 


8F 


ADC 


A 


B3 


ORA 


E 


6C 


MOV 


L,H 


90 


SUB 


B 


B4 


ORA 


H 


6D 


MOV 


L,L 


91 


SUB 


C 


B5 


ORA 


L 


6E 


MOV 


L,M 


92 


SUB 


D 


B6 


ORA 


M 


6F 


MOV 


L,A 


93 


SUB 


E 


B7 


ORA 


A 


70 


MOV 


M,B 


94 


SUB 


H 


B8 


CMP 


B 


71 


MOV 


M,C 


95 


SUB 


L 


B9 


CMP 


C 


72 


MOV 


M,D 


96 


SUB 


M 


BA 


CMP 


D 


73 


MOV 


M,E 


97 


SUB 


A 


BB 


CMP 


E 


74 


MOV 


M,H 


98 


SBB 


B 


BC 


CMP. 


H 


75 


MOV 


M,L 


99 


SBB 


C 


BD 


CMP 


L 


76 


HLT 




9A 


SBB 


D 


BE 


CMP 


M 


77 


MOV 


M,A 


9B 


SBB 


E 


BF 


CMP 


A 


78 


MOV 


A,B 


9C 


SBB 


H 


CO 


RNZ 




79 


MOV 


A,C 


9D 


SBB 


L 


CI 


POP 


B 


7k 


MOV 


A,D 


9E 


SBB 


M 


C2 


JNZ 


Adr 
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Tat 


>leF-l. (« 


:ontinued) 






OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


OP 
Code 


MNEMONIC 


C3 


JMP 




Adr 


D7 


RST 


2 


EB 


XCHG 


C4 


CNZ 




Adr 


D8 


RC 




EC 


CPE Adr 


C5 


PUSH 


B 




D9 


— 




ED 


— 


C6 


ADI 




D8 


DA 


JC 


Adr 


EE 


XRI D8 


C7 


RST 







DB 


IN 


D8 


EF 


RST 5 


C8 


RZ 






DC 


CC 


Adr 


F0 


RP 


C9 


RET 




Adr 


DD 


— 




Fl 


POP PSW 


CA 


JZ 






DE 


SBI 


D8 


F2 


JP Adr 


CB 


— 






DF 


RST 


3 


F3 


DI 


CC 


cz 




Adr 


E0 


RPO 




F4 


CP Adr 


CD 


CALL 




Adr 


El 


POP 


H 


¥5 


PUSH PSW 


CE 


ACI 




D8 


E2 


JPO 


Adr 


¥6 


ORI D8 


CF 


RST 


1 




E3 


XTHL 




¥7 


RST 6 


DO 


RNC 






E4 


CPO 


Adr 


F8 


RM 


Dl 


POP 


D 




E5 


PUSH 


H 


F9 


SPHL 


D2 


JNC 




Adr 


E6 


ANI 


D8 


FA 


JM Adr 


D3 


OUT 


D8 




E7 


RST 


4 


FB 


EI 


D4 


CNC 




Adr 


E8 


RPE 




FC 


CM Adr 


D5 


PUSH 


D 




E9 


PCHL 




FD 


— 


D6 


SUI 




D8 


EA 


JPE 


Adr 


FE 
FF 


CPI D8 
RST 7 



D8 = constant or logical/arithmetic expression that evaluates to an 8 bit quantity. 

Adr = 16-bit address. 

D16 = constant or logical/arithmetic expression that evaluates to a 16 bit data 

quantity. 
Reproduced with permission from Intel Corporation, Santa Clara, CA. 



End of Appendix F 
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Index 



$ controls, 224 
$ parameters, 221 
$ switches, 242 

$Cd, 243 

$Id, 243 

$Ld, 243 

$Od, 243 

$Sd, 243 
8080 registers, 7 
?TR macro, 135 
??, 60 



absolute file, 237 
absolute location counter, 232 
absolute object file, 231 
accumulator character, 183 
accumulator immediate instruction, 

32 
accumulator /carry operations, 37 
accumulator/register instructions, 37 
actual parameters, 5, 67, 146 

bracketed, 89 

options, 84 
additional memory switch, 239 
ADR macro, 134 
alphabetic translation, 155, 185 
ampersand, 238 

concatenation operator, 52, 86 

inside string quotes, 8 
angle brackets 

leading, 85 
apostrophe, 8 

double, 8, 75, 76, 85 

leading, 85 

quoted string, 70, 75 



arithmetic logic unit operations, 37 
arithmetic operators, 8 
ASCII strings, 8, 21, 22, 24 
assembler directives; also see 
statements 

ASEG, 232 

COMMON, 232 

CSEG, 232 

DSEG, 232 

EXTRN, 232 

NAME, 232 

PUBLIC, 232 
Assembly parameters 

1, 221 

??, 223 

A, 221 

asterisk in, 223 

controls, 224 

debugging, 225 

default, 222 

disabled, 222 

enabled, 222 

H, 221 

L, 221 

M, 221 

P, 221 

Q, 221 

S, 221 
assembly process 

computations, 10 

restart, 136 
Asterisk 

in assembly parameters, 223 

in LINK-80, 239 

leading, 4 
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B 



back-up files, 211 
base address, 25 
base page symbols, 244 
binary constant, 6 
blanks, leading, 85 
boolean tests, 145, 146, 151 
bracket nesting, 56, 85 
bracketed expressions, 89 
bracketed notation, 88 
BRN macro, 120 
BUFFERS, label, 187 



call instruction, 30 
CASE program, 187 
CASEn@m, 169 
character list, 54 
character strings, 8 
CLEAR macro, 133 
code location counter, 232 
comment field, 4 
COMPARE, 217 
COMPARE library, 149 
concatenation operator 6c, 52, 86 
condition flags, 30 
conditional assembly 

and recursion, 82 

nested, 46 

with EXITM, 58 

with IF, ELSE, ENDIF, 16-21 

with NUL operator, 46 
conditional assembly groups, 20 
conditional branching, 135 
conditional tests, 136 
constant, 6 
constant labels, 50 
control instructions, 39 



controlling identifiers, 51-56 
translated to upper-case, 55 

controlling variable, 53 

conversion 

lower to upper-case, 177 

CPI instruction, 8 

cross-reference utility, 235 



D 



data location counter, 232 

data movement instructions, 34 

data origin switch, 240 

DB instruction, 8 

DB statement, 21, 25 

DCL macro, 133 

DDT, 115, 118, 142 

debug flags, 105 

debugging 

assembly parameters, 225 

codes, 105 

full trace, 225 

iterative improvement, 225 

macro, 135 

trace code generation, 142 

traces, 105, 116, 135, 142 
debugging opcodes 

DMP, 116 

PRN msg, 116 

TRFp, 116 

TRF t, 116 

TRT, 118, 132 

TRT p, 116 

TRT t, 116 
debugging subroutines 

@AD, 133 

@CH, 133 

@HX, 133 

@IN, 133, 137 

@NB, 133 
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DEBUGP, 132, 136 
DEBUGT, 132 
decimal constant, 6 
decrement instructions, 33 
default condition 

LINK- 80, 238, 241 

RMAC, 233 
default filename, 198 
default filetype, 198 
default list device, 236 
default stack, 63 
default starting address, 14 
delimiters, 56, 84, 85 
DIF opcode, 135 
DIGIT, 216 

DIRECT macro, 180, 184, 200 
DIRECT statement, 208 
directives; see statements, 13 
directory search, 208 
dollar sign 

embedded, 4, 6 

in operand field, 7 
double apostrophes, 8, 75, 76, 85 
double semicolon, 47 
double-precision 

add instruction, 38 

storage words, 22 
DOWHILE macro, 166 
DOWHILE statement, 165 
DOWHILE-ENDDO group, 164 
drive specifications 

LINK-80, 242 
DS statement, 23 
dummy parameters, 5, 76 

unevaluated, 89 
DUP opcode, 113, 136 
DW statement, 22, 25 



ED, 3 

editor program, 92 

ELSE, 51 

ELSE statement, 19 

embedded dollar sign, 4, 6 

embedded macros, 76 

embedded question mark, 184 

empty parameters, 72 

default conditions, 199 

testing, 72 
END statement, 4, 13, 14, 25 
end-of-file character, 207 
ENDDO macro, 166 
ENDIF, 51 
ENDM statement, 58 
ENDMERGE label, 218 
ENDPR label, 207 
ENDSEL, 169, 170 
ENDW macro, 160, 161 
ENTCCP macro, 42, 46 
EQU statement, 15, 16 
equivalent expressions, 11, 12 
ERASE macro, 180, 184, 200 
error conditions 

terminal, 266 
errors 

overflow, 60 

sequence, 217 

undefined operand, 136 

value, 10 
escape characters, 89 

up arrow, 86 
escape sequences, 56^ 89 
evaluation 

macro parameters, 87-88 
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exclamation point character, 3, 8, 25 
EXITM statement, 58 
expanded macros, 76 
expressions, 11 

bracketed, 89 

RMAC, 232 

unparenthesized, 11 

well formed, 11 



false branch option, 153 

false condition, 17 

file access macros, 180 

File Control Block, 41, 198, 199, 

201 
file format 

IRL, 248 
FILE macro, 180, 198, 199 
FILE statement, 182 
FILERR label, 188 
FILLCB macro, 199 
FILLDEF macro, 198, 201 
FILLNAM macro, 198 
FILLNXT macro, 198 
FINIS macro, 180, 200 
FINIS statement, 183 
flags 

condition, 30 

debug, 105 

load overlay, 254 



GENWTST macro, 160 
GEQ macro, 135 
GET device names 

fileid, 182 

KEY, 182 

RDR (reader), 182 
GET macro, 180, 182, 201 
GET statements 

GET KEY, 182 

GET RDR, 182 

GET ZOT, 182 
go switch, 240 



H 

hexadecimal constant, 6 
HL register pair, 38, 136 



GENCASE, 172 
GENDJMP, 166 
GENDLAB, 166 
GENDTST, 166 
GENLAB macro, 160 



I 



identifiers, 3, 5, 51, 60 

controlling; see controlling 
identifiers 
IF, 16, 51 

immediate operand instructions, 32 
increment instructions, 33 
infinite substitution, 54 
inline machine code, 113 
inline macros, 49 
inline subroutines, 229 
input and output instructions, 35 
instructions 

accumulator immediate, 32 

accumulator/carry, 37 

accumulator /register, 37 

call, 30 

control, 39 

CPI, 8 

data movement, 34 
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DB, 8 

decrement, 33 

double-precision add, 38 

increment, 33 

input and output, 35 

jump, 30 

load and store direct, 35 

load extended immediate, 32 

LXI, 8 

move immediate, 32 

RDM, 113 

restart, 30 

return, 30 

stack pop and push, 35 

WRM, 118 
IRL file, 237 

format, 248 
IRP-ENDM group, 54 
IRPC-ENDM group, 51 
iterative improvement, 225 



jump instruction, 30 



labels, 5 

BUFFERS, 187 

constant, 50 

ENDMERGE, 217 

ENDPR, 207 

FILERR, 188 

MASLOW, 217 

optional, 22 

SAME, 217 

START, 217 

unique, 46, 47 

with leading ??, 60 
leading characters 

??, 60 

angle brackets, 84, 85 

apostrophe, 85 

asterisk, 4 

blanks, 85 

double apostrophe, 85 

percent, 85 

semicolon, 4 

string quotes, 85 

tabs, 85 

x, 85 
LIB- 80 switches, 263 
line#, 3 



label field, 3 
label generators 
GENCASE, 170 
GENDJMP, 166 
GENDLAB, 166 
GENDTST, 166 
GENELT, 170 
GENSLAB, 170 
GENSLXI, 170 
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LINK-80 

default condition, 238, 241 

multiline commands, 238 

run-time parameters, 239 
LINK-80 switches, 239-242 

additional memory, 239 

data origin, 240 

go, 240 

load address, 240 

memory size, 241 

no list, 241 

no recording of symbols, 241 

output COM file, 241 

output PRL file, 241 

program origin, 241 

? symbol, 242 

search, 242 

$, 242-244 
listing device, 77 
LIT opcode, 133 
literal values, 1 
load address switch, 240 
load and store direct instructions, 35 
load extended immediate instructions, 

32 
Load Flag 

overlays, 254 
local stack, 42 
LOCAL statement, 46, 60 
logical operators, 8 
lower-case names, 7 
LSR macro, 135 
LSR opcode, 113 
LXI H instruction, 7 



M 

machine emulation, 145 
MACLIB statement, 92 
macro calls 

multiple, 46 
macro debugging; see debugging, 225 
macro definitions, 76 

nested, 76 
macro error messages, 265 
macro groups 

DOWHILE-ENDDO, 164 

IRP-ENDM, 54 

IRPC-ENDM, 51 

MACRO-ENDM, 66 

nested WHEN-ENDW, 159 

REPT group, 50 

REPT-ENDM, 49 

SELECT-ENDSEL, 169 

WHEN-ENDW, 159 
macro invocation, 82 
macro libraries 

COMPARE, 149 

comprehensive, 188 

DOWHILE statement, 165 

expanded NCOMPARE, 153 

NCOMPARE, 153, 155 

SELECT statement, 171 

SEQIO, 187, 188, 218 

stack machine, 121 

WHEN, 160 

WHEN statement, 161 

Zilog Z80, 92 
macro opcodes 

machine emulation, 145 
macro redefinition, 79 
macro storage, 228 
macro subroutines, 79 
MACRO-ENDM group, 66 
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macros 
?TR, 135 
ADR, 134, 135 
BRN, 136 
CLEAR, 133 
DCL, 133 
debugging, 135 
DIRECT, 180, 184 
DOWHILE, 165 
embedded, 76 
ENDDO, 166 
ENDW, 159, 160 
ENTCCP, 42, 46 
ERASE, 180, 184 
expansion, 76 
FILE, 198 
FILLFCB, 199 
FILLDEF, 198, 201 
FILLNAM, 198 
FILLNXT, 198 
GENLAB, 160 
GENWTST, 160 
GEQ, 135 
GET, 201 
inline, 49 
LSR, 135 
MOVE, 79 
negated, 153 
NEQ, 151 
NULMAC, 73 
OUTPUT, 77 
predefined, 92 
PRINT, 70 
PUT, 175, 201 
RDM, 136 
READ, 149 
RENAME, 184 
REST, 133, 135 
RESTORE, 70 
RWTRACE, 136 



SAVE, 68, 133, 136 

SELECT, 170 

SETIO, 77 

SIZ, 133, 136 

TEST?, 147, 151 

TIMER, 99 

TYPEOUT, 46 

VAL, 135 

WCHAR, 82 

WHEN, 160, 161 

WRITE, 145 

XIT, 136 
macros; also see file access macros 
MASLOW label, 217 
master back-up, 211, 218 
master record, 211 
master sequence number, 218 
Memory Map, 237 
memory size switch, 241 
MERGE program, 211, 216, 217 
move immediate instruction, 32 
MOVE macro, 79 
multiline commands 
LINK-80, 238 
multiple macro calls, 46 
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N 

name field 

optional, 246 
names 

overlay, 255 
NCOMPARE library, 153 
negated macro, 153 
negative values, 10 
NEQ macro, 151 
nested macro definitions, 76-77 
nested macro groups, 159 
nested overlays, 256 
nesting level restriction, 21 
NEXTSEL, 169 
no list switch, 241 
no recording symbols switch, 241 
nonmacro labels, 5 
nonzero value, 19 
notation 

bracketed, 88 
NUL operator, 10, 72, 75 
null parameters, 72 
null string, 54 
NULMAC macro, 73 
numeric constants, 6 



o 



octal constant, 6 
one-character strings, 8 
opcode emulation, 108 
opcodes 

debugging; see debugging opcodes 

DIF, 135 

DUP, 113, 136 

LIT, 133 

LSR, 113 

PRN, 142 

SUM, 135 



TRT T, 138 

WRM, 113, 137 
operand field, 10 
operand 

undefined error, 136 

undefined message, 136 
operation codes, 29 
operation field, 4, 5 
operators 

ampersand, 52, 55 

arithmetic, 8 

concatenation, 52, 86 

logical, 9 

NUL, 10, 72, 75 

precedence of, 11 

relational, 9 
optional label, 23 
optional name field, 246 
optional value field, 246 
options 

false branch, 153 
ORG statement, 14 
output COM file switch, 241 
OUTPUT macro, 77 
output PRL file switch, 241 
overflow error, 60 
overlapping overlays, 259 
Overlay Manager, 251 
overlays 

in command line, 255 

in PL /I programs, 252 

methods, 252, 254 

names, 255 

nested, 252, 256 

origins, 251 

overlapping, 259 

PL/I, 251, 252 

restrictions, 252 

specification, 255 

tree structure, 251 
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page 

breaks, 24 

ejects, 24 

size, 25 
PAGE statement, 23 
parameter evaluation, 84-86 

conventions, 84 

example, 87 
parameter specifications, 221 
parameters 

actual; see actual parameters 

dummy; see dummy parameters 

empty; see empty parameters 

run-time, 239 
percent character, 85 
percent operator, 151 
PL/I overlays, 252 
plus sign, 49 
predefined macros, 92 
PRINT 

macro, 70 

program, 202, 207 

subroutine, 62 
PRN 

macro, 132 

opcodes, 142 
program control structures, 145, 158 
program origin switch, 241 
program starting address, 13, 14 
prototype statements, 67, 68, 70, 77 

plus sign, 68 

recursive macros, 82 

redefining, 79 



Pseudo operations, 13, 25 

DB, 13 

DS, 13 

DW, 13 

ELSE, 13, 51 

END, 13 

ENDIF, 13 

EQU, 13 

EXITM, 58 

IF, 13, 51 

IRP, 41 

IRPC, 41 

ORG, 3 

PAGE, 13 

REPT, 41, 49 

SET, 13 

TITLE, 13 
PUT 

device names, 183 

macro, 182, 200 
PUT statements 

PUT CON, 183 

PUT LST, 183 

PUT PUN, 183 

PUT ZAP, 183 



Q 

question mark 

embedded, 184 
quoted strings, 75, 89 
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R 



radix indicators, 6 

Random Access Memory, 101 

RDM instruction, 113 

RDM macro, 136 

READ macro, 149 

READM, 216 

READU, 216 

records 

updated, 211 
recursion, 82 
recursive macros 

invocation, 82 

prototype statements, 82 
redefinition of macros, 79 
register-to-register move instructions, 

34 
registers, restoring, 70 
REL file, 262 
relational operators, 8 
relocatable object code 

LINK- 80, 249 
relocatable object file, 231 
relocatable object module, 237, 244 
RENAME macro, 180, 184, 201 
REPT group, 49 
REPTloop, 113 
REPT-ENDM group, 49 
reserved symbols, 228 
reserved words, 7, 13 
REST macro, 133, 135 
restart instruction, 30 
RESTORE macro, 67 
restrictions 

overlays, 251, 252 
return instruction, 30 
RMAC 

default condition, 233 

expressions, 232 



run-time error messages 

LINK-80, 271 
run-time parameters, 239 
RWTRACE macro, 136 



SAME label, 217 
SAVE macro, 67, 133, 136 
search switch, 242 
SELECT group 

CASEn@m, 169 

ENDSEL, 169 

NEXTSEL, 169 

SELVn, 169 
SELECT macro, 170 
SELECT-ENDSEL group, 169 
select vector, 169 
SELNEXT, 170, 172 
SELVn, 169 
semicolon 

double, 47 

leading, 4 
SEQERR, 217 
SEQIO library, 218 
sequence errors, 217 
SET statement, 16, 188 
SETIO macro, 77 
SID, 237 

single-character commands, 177, 180 
single-character escape, 86 
single-character flags, 265 
single-precision storage, 21 
SIZ macro, 111, 136 
source program line number, 3 
special characters 

LINK-80, 242 
special link items, 246 
stack machine macro library, 111 
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stack pointer, 42 

stack pop and push instructions, 35 
START label, 46, 217 
statement elements 

comment, 3 

label, 3 

line#, 3 

operand, 3 

operation, 3 
statements 

ASEG, 232 

COMMON, 232 

CSEG, 232 

DB, 25 

DIRECT, 208 

DS, 23 

DSEG, 232 

DW, 25 

ELSE, 16 

END, 13, 14 

ENDM, 58 

EQU, 13, 15 

EXITM, 58 

EXTRN, 232 

FILE, 182, 199 

FINIS, 183 

IF, 16 

LOCAL, 46, 60 

MACLIB, 92 

NAME, 232 

ORG, 13 

prototype; see prototype statements 

PAGE, 23 

PUBLIC, 232 

PUT, 182 

SET, 16, 188 

TITLE, 24 
storage words 

double-precision, 22 



storage 

in symbol table, 229 

macro, 228 

single-precision, 21 

symbol table, 229 
string characters, 22 
string constants, 8, 24 
string quotes, 53, 86, 89 
subexpressions, 11 
subroutines 

inline, 229 

PRINT, 62 
subroutines; also see utility 

subroutines 
substitution 

dummy parameters, 86-87 

infinite, 86 

rules, 56 
SUM opcode, 135 
switches 

LIB-80, 263 

LINK- 80; see LINK- 80 switches 
SYM file, 208 

symbol storage requirements, 227 
symbol table, 47 

overflow message, 229 

storage, 227, 229 

temporary storage, 229 
symbols 

Base Page, 244 

defined in equates, 244 

relocatable in Base Page, 244 

undefined, 256 

user-defined, 242 
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w 



tab characters, 1, 3 

leading, 86 
terminal error conditions, 267-268 
TEST? macro, 147, 151 
TIMER macro, 97 
TITLE statement, 24 
tree structured overlays, 251 
TRT T opcode, 138 
two-character strings, 8 
TYPE command, 217 
TYPEOUT macro, 46 



WCHAR macro, 67 
well-formed expressions, 11 
WHEN macro, 160, 161 
WHEN macro library, 160 
WHEN-ENDW group, 158 
WRITE macro, 145 
WRITE statement, 168 
WRITESEQ, 217 
WRM instruction, 116 
WRM opcode, 113, 114, 137 



U 



UGEN macro, 132 
undefined operand error, 136 
undefined operand message, 136 
undefined symbols, 256 
unique label, 46, 52 
up arrow as escape character, 86 
update back-up, 211 
update records, 211 
upper-case names, 7 
Use Factor, 237 
user-defined symbols, 242 
utility subroutines, 46, 216 



X 

XIT macro, 136 
XREF, 235 



Z 

zero value, 19 



V 

VAL macro, 135 
value errors, 10 
value field 

optional, 246 
values 

negative, 10 
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2. What suggestions do you have for improving this manual? What information 
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3. Did you find errors in this manual? (Specify section and page number.] 
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